@sodax/skills 2.0.0-rc.10

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

@@ -0,0 +1,181 @@
+# Token migration — `MigrationService`
+
+Migration of legacy ICON ecosystem tokens to the SODAX hub. Three sub-services:
+
+- **`IcxMigrationService`** — ICX/wICX → SODA (forward) and SODA → ICX (revert).
+- **`BnUSDMigrationService`** — legacy bnUSD (ICON / Sui / Stellar) ↔ new bnUSD (EVM chains) via vault transformations.
+- **`BalnSwapService`** — BALN → SODA with lockup periods (0–24 months) that multiply rewards (0.5x–1.5x).
+
+Access: `sodax.migration`. Service class: `MigrationService` (with sub-services `sodax.migration.icxMigration`, `sodax.migration.bnUSDMigrationService`, `sodax.migration.balnSwapService`). Feature tag for errors: `'migration'`.
+
+> Don't confuse this feature (the `MigrationService` SDK module) with the v1 → v2 SDK port itself. They share the word "migration" but are independent concerns. The v1 → v2 port playbook lives at [`features/migration.md`](../../../migration-v1-to-v2/knowledge/features/migration.md).
+
+## How it works
+
+All three sub-services follow the same pattern: deposit on a spoke chain → relay to hub → execute hub-side migration contract → deliver new token.
+
+`MigrationService` exposes 11 async public methods:
+
+- 4 orchestrators (full execution): `migratebnUSD`, `migrateIcxToSoda`, `revertMigrateSodaToIcx`, `migrateBaln`.
+- 4 intent creators (raw or signed spoke tx, no full lifecycle): `createMigrateBnUSDIntent`, `createMigrateIcxToSodaIntent`, `createRevertMigrateSodaToIcxIntent`, `createMigrateBalnIntent`.
+- `approve`, `isAllowanceValid` (action-discriminated like staking and money market).
+- `getAvailableAmount` (read-only; `IcxMigrationService` only — checks how much SODA the user can claim from a partial migration).
+
+`BalnSwapService` has additional lock-management methods that **still throw** (do not return `Result<T>`): `claim`, `claimUnstaked`, `stake`, `unstake`, `cancelUnstake`, `getDetailedUserLocks`. This is deliberate tech debt; future cleanup. Wrap them in `try/catch` until then.
+
+## Public methods
+
+```ts
+sodax.migration.migratebnUSD<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.migration.migrateIcxToSoda<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.migration.revertMigrateSodaToIcx<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.migration.migrateBaln<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+
+sodax.migration.createMigrateBnUSDIntent<K, Raw>(...): Promise<Result<...>>;
+// + 3 other createXxxIntent methods
+
+sodax.migration.approve<K, Raw>(args): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
+sodax.migration.isAllowanceValid<K, Raw>(args): Promise<Result<boolean, SodaxError>>;
+
+sodax.migration.icxMigration.getAvailableAmount(): Promise<Result<bigint, SodaxError>>;
+
+// BalnSwapService — STILL THROW (tech debt; not Result-wrapped):
+sodax.migration.balnSwapService.claim(...): Promise<TxReturnType<K, false>>;
+sodax.migration.balnSwapService.claimUnstaked(...): Promise<TxReturnType<K, false>>;
+sodax.migration.balnSwapService.stake(...): Promise<TxReturnType<K, false>>;
+sodax.migration.balnSwapService.unstake(...): Promise<TxReturnType<K, false>>;
+sodax.migration.balnSwapService.cancelUnstake(...): Promise<TxReturnType<K, false>>;
+sodax.migration.balnSwapService.getDetailedUserLocks(...): Promise<DetailedUserLocks>;
+```
+
+## Action params shape
+
+```ts
+type MigrationParams<K extends SpokeChainKey> = {
+  srcChainKey: K;
+  srcAddress: GetAddressType<K>;
+  amount: bigint;
+  dstAddress?: string;
+};
+
+type UnifiedBnUSDMigrateParams<K> = MigrationParams<K> & {
+  srcToken: `0x${string}`;       // legacy or new bnUSD; SDK detects direction from address
+  dstToken: `0x${string}`;       // the other side
+};
+
+type IcxToSodaMigrateParams<K> = MigrationParams<K>;
+type RevertSodaToIcxParams<K> = MigrationParams<K>;
+type BalnSwapParams<K> = MigrationParams<K> & {
+  lockPeriodMonths: 0 | 1 | 2 | 3 | 6 | 12 | 18 | 24;  // reward multiplier 0.5x – 1.5x
+};
+```
+
+## Common call shapes
+
+### bnUSD migrate (forward — legacy → new, e.g. ICON → BASE)
+
+```ts
+const result = await sodax.migration.migratebnUSD({
+  params: {
+    srcChainKey: ChainKeys.ICON_MAINNET,
+    srcAddress: 'hx…',
+    srcToken: '0x…',  // legacy bnUSD on ICON
+    dstToken: '0x…',  // new bnUSD on BASE
+    amount: parseUnits('100', 18),
+    dstAddress: '0x…',
+  },
+  raw: false,
+  walletProvider: iconWp,
+});
+
+if (!result.ok) return;
+const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+The SDK auto-detects direction from `(srcToken, dstToken)` addresses; the `direction` field surfaces on `error.context` if it fails (`'forward' | 'reverse'`).
+
+### ICX → SODA
+
+```ts
+await sodax.migration.migrateIcxToSoda({
+  params: { srcChainKey: ChainKeys.ICON_MAINNET, srcAddress: 'hx…', amount },
+  raw: false,
+  walletProvider: iconWp,
+});
+```
+
+### Revert SODA → ICX
+
+```ts
+await sodax.migration.revertMigrateSodaToIcx({
+  params: { srcChainKey: ChainKeys.SONIC_MAINNET, srcAddress: '0x…', amount },
+  raw: false,
+  walletProvider: sonicWp,
+});
+```
+
+### BALN → SODA with lockup
+
+```ts
+await sodax.migration.migrateBaln({
+  params: {
+    srcChainKey: ChainKeys.ICON_MAINNET,
+    srcAddress: 'hx…',
+    amount: parseUnits('1000', 18),
+    lockPeriodMonths: 12,    // 1.0x base; 24 is 1.5x; 0 is 0.5x
+  },
+  raw: false,
+  walletProvider: iconWp,
+});
+```
+
+### Approve / allowance — action-discriminated
+
+```ts
+await sodax.migration.approve({
+  params: { srcChainKey, srcAddress, amount, action: 'migratebnUSD' /* or 'migrateIcxToSoda' | 'revertMigrateSodaToIcx' | 'migrateBaln' */ },
+  raw: false,
+  walletProvider,
+});
+```
+
+### BALN lock management (carve-out — still throws)
+
+```ts
+try {
+  const tx = await sodax.migration.balnSwapService.stake({ /* … */ });
+} catch (e) {
+  // Handle as v1-style throw. Result wrapping for these methods is on the roadmap.
+}
+```
+
+## Return shapes
+
+| Method | Success type |
+|---|---|
+| 4 orchestrators (`migratebnUSD`, `migrateIcxToSoda`, `revertMigrateSodaToIcx`, `migrateBaln`) | `TxHashPair` |
+| 4 intent creators | `CreateIntentResult<K, Raw>` |
+| `approve` | `TxReturnType<K, Raw>` |
+| `isAllowanceValid` | `boolean` |
+| `getAvailableAmount` | `bigint` |
+| `BalnSwapService.claim` etc. | `TxReturnType<K, false>` (raw, not `Result`-wrapped) |
+
+## Error codes
+
+`feature: 'migration'`. Per-method narrow unions:
+
+| Method | Codes | `error.context.action` | Notes |
+|---|---|---|---|
+| `migratebnUSD` | full exec set incl. `TX_VERIFICATION_FAILED` | `'migratebnUSD'` | `error.context.direction: 'forward' \| 'reverse'`. Has secondary `phase: 'destinationExecution'` for the bnUSD `waitUntilIntentExecuted` watcher. |
+| `migrateIcxToSoda` | full exec set | `'migrateIcxToSoda'` | |
+| `revertMigrateSodaToIcx` | full exec set | `'revertMigrateSodaToIcx'` | |
+| `migrateBaln` | full exec set | `'migrateBaln'` | |
+| `create*Intent` | `VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `UNKNOWN` | matches | |
+| `approve` | `VALIDATION_FAILED`, `APPROVE_FAILED`, `UNKNOWN` | matches | |
+| `isAllowanceValid` | `VALIDATION_FAILED`, `ALLOWANCE_CHECK_FAILED`, `UNKNOWN` | n/a | |
+| `getAvailableAmount` | `VALIDATION_FAILED`, `LOOKUP_FAILED`, `UNKNOWN` | n/a | `method: 'getAvailableAmount'` |
+
+## Cross-references
+
+- v1 → v2 migration of this feature: [`features/migration.md`](../../../migration-v1-to-v2/knowledge/features/migration.md).
+- Architecture (relay layer's `phase: 'destinationExecution'` for bnUSD): [`../architecture.md`](../architecture.md) § 9.

package/skills/sodax-sdk/integration/knowledge/features/money-market.md

@@ -0,0 +1,198 @@
+# Money Market — `MoneyMarketService`
+
+Cross-chain lending and borrowing. Supply, borrow, withdraw, repay across 19 spoke chains. Position state lives on the hub.
+
+Access: `sodax.moneyMarket`. Service class: `MoneyMarketService`. Feature tag for errors: `'moneyMarket'`.
+
+## How it works
+
+A user supplies on a spoke chain; the SDK relays the deposit to the hub, where the position is recorded against the user's hub wallet abstraction. Borrow can deliver funds back to the same chain (same-chain borrow) or to a different spoke chain (cross-chain borrow). Withdraw and repay reverse the flow.
+
+aTokens (ERC4626 receipt tokens) live on the hub and represent the user's share of each reserve. Use `sodax.moneyMarket.getAToken(...)` to look them up.
+
+## Public methods
+
+```ts
+// Mutations
+sodax.moneyMarket.supply<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.moneyMarket.borrow<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.moneyMarket.withdraw<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.moneyMarket.repay<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+
+// Intent creators (raw-tx variant)
+sodax.moneyMarket.createSupplyIntent<K, Raw>(...): Promise<Result<...>>;
+sodax.moneyMarket.createBorrowIntent<K, Raw>(...): Promise<Result<...>>;
+sodax.moneyMarket.createWithdrawIntent<K, Raw>(...): Promise<Result<...>>;
+sodax.moneyMarket.createRepayIntent<K, Raw>(...): Promise<Result<...>>;
+
+// Approve + allowance (action-discriminated)
+sodax.moneyMarket.approve<K, Raw>(args): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
+sodax.moneyMarket.isAllowanceValid<K>(args): Promise<Result<boolean, SodaxError>>;
+
+// Estimation
+sodax.moneyMarket.estimateGas<K>(params): Promise<Result<GetEstimateGasReturnType<K>, SodaxError>>;
+
+// Reads (sync — config-derived, no I/O)
+sodax.moneyMarket.getSupportedTokens(): GetMoneyMarketTokensApiResponse;
+sodax.moneyMarket.getSupportedTokensByChainId(chainKey): readonly XToken[];
+sodax.moneyMarket.getSupportedReserves(): readonly Address[];
+
+// Hub-side calldata builders (Hex outputs; pre-flight inspection / custom orchestration)
+sodax.moneyMarket.buildSupplyData(srcChainKey, fromToken, amount, toHubAddress): Hex;
+sodax.moneyMarket.buildBorrowData(...): Hex;
+sodax.moneyMarket.buildWithdrawData(...): Hex;
+sodax.moneyMarket.buildRepayData(...): Hex;
+```
+
+For per-position user reads (reserves data, user reserves data, formatted summaries, aToken balances, etc.) the entrypoint is `sodax.backendApi`, not `MoneyMarketService` — see [`backend-api.md`](backend-api.md) for `getMoneyMarketPosition`, `getAllMoneyMarketAssets`, `getMoneyMarketAsset`, `getMoneyMarketAssetBorrowers`, `getMoneyMarketAssetSuppliers`, `getAllMoneyMarketBorrowers`.
+
+## Action params shape
+
+`MoneyMarketParams<K>` is the shared base:
+
+```ts
+type MoneyMarketParams<K extends SpokeChainKey> = {
+  srcChainKey: K;
+  srcAddress: GetAddressType<K>;
+  token: `0x${string}`;     // hub asset address
+  amount: bigint;
+};
+```
+
+Per-action params:
+
+```ts
+type MoneyMarketSupplyParams<K> = MoneyMarketParams<K> & { action: 'supply' };
+type MoneyMarketWithdrawParams<K> = MoneyMarketParams<K> & { action: 'withdraw' };
+
+type MoneyMarketBorrowParams<K> = MoneyMarketParams<K> & {
+  action: 'borrow';
+  dstChainKey?: SpokeChainKey;   // delivery chain; defaults to srcChainKey
+  dstAddress?: string;
+};
+type MoneyMarketRepayParams<K> = MoneyMarketParams<K> & {
+  action: 'repay';
+  dstChainKey?: SpokeChainKey;   // debt chain; defaults to srcChainKey
+  dstAddress?: string;
+};
+```
+
+## Common call shapes
+
+### Supply (same-chain)
+
+```ts
+const result = await sodax.moneyMarket.supply({
+  params: {
+    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
+    srcAddress: '0x…',
+    token: USDC.address,
+    amount: parseUnits('100', 6),
+    action: 'supply',
+  },
+  raw: false,
+  walletProvider: evmWp,
+});
+
+if (!result.ok) return;
+const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+### Borrow (cross-chain)
+
+Borrow on Arbitrum, deliver USDC to Stellar:
+
+```ts
+await sodax.moneyMarket.borrow({
+  params: {
+    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
+    srcAddress: '0x…',
+    token: USDC_ARBITRUM.address,
+    amount: parseUnits('50', 6),
+    action: 'borrow',
+    dstChainKey: ChainKeys.STELLAR_MAINNET,
+    dstAddress: 'G…',
+  },
+  raw: false,
+  walletProvider: evmWp,
+});
+```
+
+Same-chain borrow: omit `dstChainKey` and `dstAddress`.
+
+### Repay (cross-chain — pay from a different chain than the debt)
+
+```ts
+await sodax.moneyMarket.repay({
+  params: {
+    srcChainKey: ChainKeys.BASE_MAINNET,            // funds come from here
+    srcAddress: '0x…',
+    token: USDC_BASE.address,
+    amount: parseUnits('50', 6),
+    action: 'repay',
+    dstChainKey: ChainKeys.ARBITRUM_MAINNET,        // debt lives here
+    dstAddress: '0x…',
+  },
+  raw: false,
+  walletProvider: baseWp,    // wallet signs on the FROM chain (BASE)
+});
+```
+
+### Approve / allowance check
+
+```ts
+await sodax.moneyMarket.approve({
+  params: { srcChainKey, srcAddress, token, amount, action: 'supply' },
+  raw: false,
+  walletProvider: evmWp,
+});
+
+const allowed = await sodax.moneyMarket.isAllowanceValid({
+  params: { srcChainKey, srcAddress, token, amount, action: 'supply' },
+});
+```
+
+The `action` field routes to the right token under the hood — relevant for repay where the spent token may differ from the supplied token.
+
+## Return shapes
+
+| Method | Success type |
+|---|---|
+| `supply`, `borrow`, `withdraw`, `repay` | `TxHashPair` = `{ srcChainTxHash, dstChainTxHash }` |
+| `create*Intent` | `CreateIntentResult<K, Raw>` |
+| `approve` | `TxReturnType<K, Raw>` |
+| `isAllowanceValid` | `boolean` |
+| `estimateGas` | `GetEstimateGasReturnType<K>` (chain-family-specific) |
+| `getSupportedTokens` | `GetMoneyMarketTokensApiResponse` (record of chains → token arrays) |
+| `getSupportedTokensByChainId` | `readonly XToken[]` |
+| `getSupportedReserves` | `readonly Address[]` |
+| `buildSupplyData` / `buildBorrowData` / `buildWithdrawData` / `buildRepayData` | `Hex` (calldata for hub-side calls) |
+
+> Every cross-chain mutation across the SDK (bridge, staking, dex, migration, MM) returns `TxHashPair = { srcChainTxHash, dstChainTxHash }` — there is no array-form variant in v2.
+
+## Error codes
+
+`feature: 'moneyMarket'`. Per-method narrow unions:
+
+| Method | Codes | `error.context.action` |
+|---|---|---|
+| `supply` | full exec set | `'supply'` |
+| `borrow` | full exec set | `'borrow'` |
+| `withdraw` | full exec set | `'withdraw'` |
+| `repay` | full exec set | `'repay'` |
+| `create*Intent` | `VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `UNKNOWN` | matches action |
+| `approve` | `VALIDATION_FAILED`, `APPROVE_FAILED`, `UNKNOWN` | matches action |
+| `isAllowanceValid` | `VALIDATION_FAILED`, `ALLOWANCE_CHECK_FAILED`, `UNKNOWN` | matches action |
+| Read methods | `VALIDATION_FAILED`, `LOOKUP_FAILED`, `UNKNOWN` | (use `error.context.method`) |
+
+"Full exec set" = `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| EXECUTION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| UNKNOWN`.
+
+## RAY precision math
+
+Aave's RAY precision (27 decimals) is used for interest calculations under the hood. Raw RAY values flow through `BackendApiService.getMoneyMarketAsset` / `getMoneyMarketPosition` (via `sodax.backendApi`); pre-formatted user-facing values come from the same backend service. Don't simplify the precision handling — porting Aave's `RayMath`/`PercentageMath` losslessly is a load-bearing requirement.
+
+## Cross-references
+
+- v1 → v2 money market migration: [`features/money-market.md`](../../../migration-v1-to-v2/knowledge/features/money-market.md).
+- Architecture (hub-side wallet abstraction, ConfigService): [`../architecture.md`](../architecture.md) §§ 3, 4.
+- Stellar destinations need a trustline: [`../chain-specifics.md`](../chain-specifics.md).

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

@@ -0,0 +1,63 @@
+# Partner — `PartnerService`
+
+Partner-fee handling. `PartnerService` itself only exposes `feeClaim: PartnerFeeClaimService` and `config: ConfigService` as public fields. Every operation lives on `sodax.partners.feeClaim`.
+
+Access: `sodax.partners`. Service class: `PartnerService` (operations on `sodax.partners.feeClaim`). Feature tag for errors: `'partner'`.
+
+## Methods (all on `sodax.partners.feeClaim`)
+
+```ts
+// Token approval
+sodax.partners.feeClaim.isTokenApproved({ token, srcAddress }): Promise<Result<boolean, Error>>;
+sodax.partners.feeClaim.approveToken<Raw>(args): Promise<Result<TxReturnType, Error>>;
+
+// Auto-swap preferences (whether partner-collected fees auto-swap into a target asset)
+sodax.partners.feeClaim.getAutoSwapPreferences(queryAddress): Promise<Result<AutoSwapPreferences, Error>>;
+sodax.partners.feeClaim.setSwapPreference<K, Raw>(args): Promise<Result<TxReturnType, Error>>;
+
+// Fee claim flows
+sodax.partners.feeClaim.swap(args): Promise<Result<...>>;                           // immediate fee swap
+sodax.partners.feeClaim.createIntentAutoSwap<Raw>(args): Promise<Result<...>>;       // intent-driven auto-swap
+
+// Reads
+sodax.partners.feeClaim.fetchAssetsBalances(args): Promise<Result<...>>;
+sodax.partners.feeClaim.getOriginalAssetAddress(chainId, hubAsset): OriginalAssetAddress | undefined;
+sodax.partners.feeClaim.getSpokeTokenFromOriginalAssetAddress(...): /* … */;
+```
+
+## Common call shape
+
+```ts
+// 1. Check whether the partner's fee token is approved on the hub:
+const approved = await sodax.partners.feeClaim.isTokenApproved({
+  token: '0x…',         // hub asset address
+  srcAddress: partnerAddress,
+});
+
+// 2. Approve once if not:
+if (approved.ok && !approved.value) {
+  await sodax.partners.feeClaim.approveToken({
+    params: { token: '0x…', amount: 2n ** 256n - 1n },
+    raw: false,
+    walletProvider: sonicWp,
+  });
+}
+
+// 3. Configure auto-swap preference (one-time):
+await sodax.partners.feeClaim.setSwapPreference({
+  params: { /* preference fields */ },
+  raw: false,
+  walletProvider: sonicWp,
+});
+```
+
+## Error codes
+
+`feature: 'partner'`. Action methods get the full exec set; reads get `LookupErrorCode` partitioned by `error.context.method`.
+
+## Cross-references
+
+- v1 → v2 migration of `PartnerService`: [`features/partner.md`](../../../migration-v1-to-v2/knowledge/features/partner.md).
+- Hub-wallet asset recovery (separate service): [`./recovery.md`](recovery.md).
+- Backend HTTP client (separate service): [`./backend-api.md`](backend-api.md).
+- Error model context fields (`error.context.api`, `error.context.method`): [`../reference/`](../reference/) § 3.

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

@@ -0,0 +1,50 @@
+# Recovery — `RecoveryService`
+
+Withdraw stuck assets from a user's hub-wallet abstraction back to a spoke chain. Useful when a cross-chain operation deposited to the hub but the destination step failed (e.g. relay timeout after the spoke tx landed).
+
+Access: `sodax.recovery`. Service class: `RecoveryService`. Feature tag for errors: `'recovery'`.
+
+## Methods
+
+```ts
+// Read: list balances of all known hub assets in a user's hub wallet abstraction.
+sodax.recovery.fetchHubAssetBalances(args): Promise<Result<HubAssetBalance[], SodaxError>>;
+
+// Mutation: withdraw a single hub asset back to a spoke chain.
+// Returns a tx-pair when raw: false (the hub-side spend + the relayed spoke-side receive).
+sodax.recovery.withdrawHubAsset<K extends SpokeChainKey, Raw extends boolean>(
+  action: WithdrawHubAssetAction<K, Raw>,
+): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
+```
+
+## Common call shape
+
+```ts
+// 1. Find what's stuck on the hub for this user:
+const balances = await sodax.recovery.fetchHubAssetBalances({ /* user / hub-wallet args */ });
+if (!balances.ok || balances.value.length === 0) return;
+
+// 2. Withdraw one entry back to a spoke chain:
+const result = await sodax.recovery.withdrawHubAsset({
+  params: {
+    /* hub-asset address, amount, destination spoke chain key, destination address */
+  },
+  raw: false,
+  walletProvider: sonicWp,
+});
+```
+
+## Error codes
+
+`feature: 'recovery'`. The mutation method returns the full exec set (including relay codes); the read method returns `LookupErrorCode` partitioned by `error.context.method`.
+
+## When to use
+
+Recovery is a workaround for failed cross-chain operations. Best used **after** investigating why the original operation failed — relay timeouts may resolve on retry; structural failures need fixing first.
+
+## Cross-references
+
+- v1 → v2 migration of `RecoveryService`: [`features/recovery.md`](../../../migration-v1-to-v2/knowledge/features/recovery.md) (note: service is new in v2 — no v1 equivalent).
+- Partner-fee handling (separate service): [`./partner.md`](partner.md).
+- Backend HTTP client (separate service): [`./backend-api.md`](backend-api.md).
+- Error model context fields: [`../reference/`](../reference/) § 3.

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

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