@sodax/skills 2.0.0-rc.8 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (168) hide show
  1. package/.claude-plugin/plugin.json +1 -0
  2. package/AGENTS.md +123 -13
  3. package/README.md +5 -2
  4. package/package.json +1 -1
  5. package/skills/sodax-build/SKILL.md +90 -0
  6. package/skills/sodax-build/knowledge/README.md +35 -0
  7. package/skills/sodax-build/knowledge/brief-template.md +41 -0
  8. package/skills/sodax-build/knowledge/chains-and-assets.md +26 -0
  9. package/skills/sodax-build/knowledge/example-sessions.md +84 -0
  10. package/skills/sodax-build/knowledge/feature-catalog.md +51 -0
  11. package/skills/sodax-build/knowledge/glossary.md +35 -0
  12. package/skills/sodax-build/knowledge/handoff.md +60 -0
  13. package/skills/sodax-build/knowledge/interview-guide.md +66 -0
  14. package/skills/sodax-build/knowledge/monetization.md +37 -0
  15. package/skills/sodax-build/knowledge/use-case-gallery.md +32 -0
  16. package/skills/sodax-dapp-kit/SKILL.md +6 -2
  17. package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +65 -0
  18. package/skills/sodax-dapp-kit/bitcoin/SKILL.md +57 -0
  19. package/skills/sodax-dapp-kit/bridge/SKILL.md +59 -0
  20. package/skills/sodax-dapp-kit/dex/SKILL.md +60 -0
  21. package/skills/sodax-dapp-kit/integration/knowledge/README.md +1 -1
  22. package/skills/sodax-dapp-kit/integration/knowledge/features/README.md +3 -2
  23. package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +71 -11
  24. package/skills/sodax-dapp-kit/integration/knowledge/features/bitcoin.md +10 -6
  25. package/skills/sodax-dapp-kit/integration/knowledge/features/dex.md +2 -2
  26. package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +112 -0
  27. package/skills/sodax-dapp-kit/integration/knowledge/features/migration.md +1 -1
  28. package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +6 -1
  29. package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
  30. package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
  31. package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
  32. package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
  33. package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md +8 -8
  34. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +168 -0
  35. package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
  36. package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +4 -4
  37. package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
  38. package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md +3 -0
  39. package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md +1 -1
  40. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +67 -6
  41. package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +49 -0
  42. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +54 -0
  43. package/skills/sodax-dapp-kit/migration/SKILL.md +64 -0
  44. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md +1 -1
  45. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +2 -2
  46. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md +1 -1
  47. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md +1 -1
  48. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +19 -10
  49. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md +2 -2
  50. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
  51. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
  52. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/migration.md +1 -1
  53. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +3 -3
  54. package/skills/sodax-dapp-kit/money-market/SKILL.md +61 -0
  55. package/skills/sodax-dapp-kit/staking/SKILL.md +60 -0
  56. package/skills/sodax-dapp-kit/swap/SKILL.md +64 -0
  57. package/skills/sodax-sdk/SKILL.md +54 -50
  58. package/skills/sodax-sdk/backend-api/SKILL.md +58 -0
  59. package/skills/sodax-sdk/bridge/SKILL.md +53 -0
  60. package/skills/sodax-sdk/dex/SKILL.md +54 -0
  61. package/skills/sodax-sdk/integration/knowledge/README.md +5 -3
  62. package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
  63. package/skills/sodax-sdk/integration/knowledge/architecture.md +26 -39
  64. package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
  65. package/skills/sodax-sdk/integration/knowledge/features/README.md +6 -3
  66. package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +92 -0
  67. package/skills/sodax-sdk/integration/knowledge/features/bridge.md +48 -11
  68. package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
  69. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +175 -0
  70. package/skills/sodax-sdk/integration/knowledge/features/{icx-bnusd-baln.md → migration.md} +75 -30
  71. package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
  72. package/skills/sodax-sdk/integration/knowledge/features/partner.md +86 -0
  73. package/skills/sodax-sdk/integration/knowledge/features/recovery.md +51 -0
  74. package/skills/sodax-sdk/integration/knowledge/features/staking.md +8 -3
  75. package/skills/sodax-sdk/integration/knowledge/features/swap.md +106 -22
  76. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
  77. package/skills/sodax-sdk/integration/knowledge/quickstart.md +1 -1
  78. package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -0
  79. package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
  80. package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
  81. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +34 -2
  82. package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +102 -0
  83. package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +28 -4
  84. package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
  85. package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
  86. package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
  87. package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +40 -4
  88. package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +32 -9
  89. package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
  90. package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -4
  91. package/skills/sodax-sdk/leverage-yield/SKILL.md +50 -0
  92. package/skills/sodax-sdk/migration/SKILL.md +69 -0
  93. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
  94. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +6 -10
  95. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
  96. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +3 -3
  97. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -5
  98. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +2 -2
  99. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/README.md +4 -2
  100. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +92 -0
  101. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
  102. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
  103. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/{icx-bnusd-baln.md → migration.md} +31 -29
  104. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
  105. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +64 -0
  106. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +35 -0
  107. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +8 -3
  108. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
  109. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +19 -17
  110. package/skills/sodax-sdk/money-market/SKILL.md +56 -0
  111. package/skills/sodax-sdk/partner/SKILL.md +55 -0
  112. package/skills/sodax-sdk/recovery/SKILL.md +53 -0
  113. package/skills/sodax-sdk/staking/SKILL.md +53 -0
  114. package/skills/sodax-sdk/swap/SKILL.md +72 -0
  115. package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
  116. package/skills/sodax-wallet-sdk-core/SKILL.md +7 -3
  117. package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +54 -0
  118. package/skills/sodax-wallet-sdk-core/evm/SKILL.md +54 -0
  119. package/skills/sodax-wallet-sdk-core/icon/SKILL.md +54 -0
  120. package/skills/sodax-wallet-sdk-core/injective/SKILL.md +54 -0
  121. package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
  122. package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +2 -2
  123. package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
  124. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
  125. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
  126. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
  127. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
  128. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
  129. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
  130. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
  131. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
  132. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
  133. package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
  134. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
  135. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
  136. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/testing.md +1 -1
  137. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
  138. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
  139. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
  140. package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
  141. package/skills/sodax-wallet-sdk-core/near/SKILL.md +54 -0
  142. package/skills/sodax-wallet-sdk-core/solana/SKILL.md +54 -0
  143. package/skills/sodax-wallet-sdk-core/stacks/SKILL.md +53 -0
  144. package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +54 -0
  145. package/skills/sodax-wallet-sdk-core/sui/SKILL.md +53 -0
  146. package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
  147. package/skills/sodax-wallet-sdk-react/bridge-to-sdk/SKILL.md +56 -0
  148. package/skills/sodax-wallet-sdk-react/connect/SKILL.md +59 -0
  149. package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
  150. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
  151. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
  152. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +10 -10
  153. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
  154. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +4 -4
  155. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
  156. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
  157. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
  158. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
  159. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
  160. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
  161. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/ssr-setup.md +24 -19
  162. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +1 -1
  163. package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +51 -0
  164. package/skills/sodax-wallet-sdk-react/switch-chain/SKILL.md +51 -0
  165. package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +54 -0
  166. package/skills/sodax-wallet-sdk-react/walletconnect/SKILL.md +52 -0
  167. package/skills/sodax-sdk/integration/knowledge/features/auxiliary-services.md +0 -189
  168. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/auxiliary-services.md +0 -156
@@ -40,11 +40,11 @@ sodax.dex.clService.claimRewards<K>(action): Promise<Result<TxHashPair, SodaxErr
40
40
 
41
41
  sodax.dex.clService.getPools(): PoolKey[]; // synchronous in v2
42
42
  sodax.dex.clService.getPoolData(poolKey, publicClient): Promise<Result<PoolData, SodaxError>>;
43
- sodax.dex.clService.getPositionInfo(tokenId, poolKey, publicClient): Promise<Result<PositionInfo, SodaxError>>;
43
+ sodax.dex.clService.getPositionInfo(tokenId, publicClient): Promise<Result<ClPositionInfo, SodaxError>>;
44
44
  sodax.dex.clService.getAssetsForPool(srcChainKey, poolKey): { token0, token1 }; // chain-key-first; sync
45
45
 
46
46
  // Static math helpers (still throw on error — utility class):
47
- ClService.priceToTick(price): number;
47
+ ClService.priceToTick(price, token0, token1, tickSpacing): bigint;
48
48
  ClService.calculateAmount0FromAmount1(...): bigint;
49
49
  ClService.calculateAmount1FromAmount0(...): bigint;
50
50
  ```
@@ -58,7 +58,7 @@ type CreateAssetDepositParams<K extends SpokeChainKey> = {
58
58
  asset: `0x${string}`; // spoke-side token address
59
59
  amount: bigint;
60
60
  poolToken: `0x${string}`; // hub-side pool token (vault address)
61
- dst?: { chainKey: SpokeChainKey; address: string }; // optional cross-chain delivery
61
+ dst?: { dstChainKey: SpokeChainKey; dstAddress: string }; // optional cross-chain delivery
62
62
  };
63
63
 
64
64
  type CreateAssetWithdrawParams<K> = { /* same shape */ };
@@ -67,8 +67,8 @@ type ClSupplyParams<K> = {
67
67
  srcChainKey: K;
68
68
  srcAddress: GetAddressType<K>;
69
69
  poolKey: PoolKey;
70
- tickLower: number;
71
- tickUpper: number;
70
+ tickLower: bigint;
71
+ tickUpper: bigint;
72
72
  liquidity: bigint;
73
73
  amount0Max: bigint;
74
74
  amount1Max: bigint;
@@ -117,8 +117,8 @@ const result = await sodax.dex.clService.supplyLiquidity({
117
117
  srcChainKey: ChainKeys.ARBITRUM_MAINNET,
118
118
  srcAddress: '0x…',
119
119
  poolKey: { /* { currency0, currency1, fee, tickSpacing, hooks } */ },
120
- tickLower: -887220,
121
- tickUpper: 887220,
120
+ tickLower: -887220n,
121
+ tickUpper: 887220n,
122
122
  liquidity: 1000000n,
123
123
  amount0Max: parseUnits('100', 6),
124
124
  amount1Max: parseUnits('100', 6),
@@ -0,0 +1,175 @@
1
+ # Leverage Yield — `LeverageYieldService`
2
+
3
+ Leveraged-yield ERC-4626 vaults on the Sonic hub. A vault loops supply → borrow → swap → re-supply to a target LTV, producing a leveraged long on the `asset` / `borrowToken` peg. The vault's share token (`lsoda*`) is treated as a **solver-tradeable token**, so deposits and withdrawals are intent-based swaps the service executes itself. New in v2 — no v1 equivalent.
4
+
5
+ Access: `sodax.leverageYield`. Service class: `LeverageYieldService`. Feature tag for errors: `'leverageYield'`.
6
+
7
+ ## How it works
8
+
9
+ - A vault holds `asset` (a Sodax vault token like sodaWEETH) as collateral, borrows `borrowToken` (e.g. sodaETH) from the Sodax-forked AAVE pool, swaps it back into the asset, and re-supplies — to a `targetLTV`.
10
+ - The ERC-4626 **share token is the vault proxy address itself** (`lsoda*`). Holding shares = holding the leveraged position.
11
+ - **Deposit** = swap any spoke token → `lsoda*`, delivered to the user's **hub wallet** on Sonic. **Withdraw** = swap `lsoda*` (held in the hub wallet) → any token on any chain.
12
+ - **Steady-state APR**: `netAprRay = supplyAprRay + leverageMultiplier × (supplyAprRay − borrowAprRay)`, where `leverageMultiplier = targetLTV / (1 − targetLTV)`. Rates are RAY (`1e27`); the multiplier is WAD (`1e18`). `netAprRay` goes **negative** when the borrow rate exceeds supply — for LSD-backed vaults the LSD's native staking yield (folded in by `getEffectiveApr`) is the real alpha.
13
+
14
+ ## Public methods
15
+
16
+ ```ts
17
+ // Builders — assemble a LeverageYieldSwapPayload (spread into vaultSwap). Do NOT broadcast.
18
+ sodax.leverageYield.deposit(params: LeverageYieldSwapDepositParams): Promise<Result<LeverageYieldSwapPayload, SodaxError>>;
19
+ sodax.leverageYield.withdraw(params: LeverageYieldSwapWithdrawParams): Promise<Result<LeverageYieldSwapPayload, SodaxError>>;
20
+ // withdraw sets hubWalletSwap: true; both default `deadline` from the hub block timestamp (so withdraw is async)
21
+
22
+ // Intent create + end-to-end execute (leverage-yield copies of swap's createIntent / swap)
23
+ sodax.leverageYield.createVaultIntent<K, Raw>(params: VaultSwapActionParams<K, Raw>): Promise<Result<CreateVaultIntentResult<K, Raw>, SodaxError>>;
24
+ sodax.leverageYield.vaultSwap<K>(params: VaultSwapActionParams<K, false>): Promise<Result<VaultSwapResponse, SodaxError>>;
25
+ sodax.leverageYield.notifySolver(request: { intent_tx_hash: string }): Promise<Result<SolverExecutionResponse, SodaxError>>;
26
+ // notifySolver is PUBLIC — call it to finish a manual createVaultIntent → relay → notify flow
27
+
28
+ // Sonic-direct allowance for the vault's underlying asset (the swap-style deposit handles its own approvals)
29
+ sodax.leverageYield.approve<R>(params: LeverageYieldApproveParams<R>): Promise<Result<TxReturnType<HubChainKey, R>, SodaxError>>;
30
+ sodax.leverageYield.isAllowanceValid(params: LeverageYieldAllowanceParams): Promise<Result<boolean, SodaxError>>;
31
+
32
+ // Reads (all Result<…, SodaxError> with LOOKUP_FAILED on failure)
33
+ sodax.leverageYield.getApr(vault): Promise<Result<LeverageYieldApr, SodaxError>>; // AAVE-only steady-state
34
+ sodax.leverageYield.getEffectiveApr(vault): Promise<Result<LeverageYieldEffectiveApr, SodaxError>>; // + LSD staking yield (headline)
35
+ sodax.leverageYield.getLsdApr(vault): Promise<Result<LeverageYieldLsdApr, SodaxError>>; // off-chain DefiLlama; always ok for a known vault
36
+ sodax.leverageYield.getPosition(vault): Promise<Result<LeverageYieldPosition, SodaxError>>;
37
+ sodax.leverageYield.getTotalAssets(vault): Promise<Result<bigint, SodaxError>>; // TVL
38
+ sodax.leverageYield.previewDeposit(vault, assets): Promise<Result<bigint, SodaxError>>;
39
+ sodax.leverageYield.previewWithdraw(vault, assets): Promise<Result<bigint, SodaxError>>;
40
+ sodax.leverageYield.previewRedeem(vault, shares): Promise<Result<bigint, SodaxError>>;
41
+ sodax.leverageYield.getMaxWithdraw(vault, owner): Promise<Result<bigint, SodaxError>>;
42
+ sodax.leverageYield.getMaxWithdrawForUser(vault, srcChainKey, srcAddress): Promise<Result<bigint, SodaxError>>; // dust-buffered
43
+ sodax.leverageYield.getShareBalance(vault, owner): Promise<Result<bigint, SodaxError>>;
44
+ sodax.leverageYield.getShareBalanceForUser(vault, srcChainKey, srcAddress): Promise<Result<bigint, SodaxError>>;
45
+ sodax.leverageYield.getAsset(vault): Promise<Result<Address, SodaxError>>;
46
+
47
+ // Registry (synchronous)
48
+ sodax.leverageYield.listVaults(): readonly LeverageYieldVault[];
49
+ sodax.leverageYield.getVault(name): LeverageYieldVault | undefined;
50
+ sodax.leverageYield.getVaultByAddress(address): LeverageYieldVault | undefined;
51
+ ```
52
+
53
+ ## Action params shape
54
+
55
+ ```ts
56
+ type LeverageYieldSwapDepositParams = {
57
+ vault: Address; // the lsoda* vault proxy
58
+ srcChainKey: SpokeChainKey; // chain the user holds inputToken on & signs from
59
+ srcAddress: string;
60
+ inputToken: string; // spoke-side token paid in
61
+ inputAmount: bigint;
62
+ minOutputAmount: bigint; // min lsoda* (18 dp), slippage applied
63
+ deadline?: bigint; // defaults to hub block timestamp + 5 min
64
+ solver?: Address; // 0x0 = any solver
65
+ partnerFee?: PartnerFee; // per-intent override; deducted from inputAmount before the swap
66
+ };
67
+
68
+ type LeverageYieldSwapWithdrawParams = {
69
+ vault: Address;
70
+ srcChainKey: SpokeChainKey; // chain the user signs the sendMessage on
71
+ srcAddress: string;
72
+ dstChainKey: SpokeChainKey; // where the swapped-back token is delivered
73
+ outputToken: string;
74
+ inputAmount: bigint; // lsoda* shares to burn (18 dp)
75
+ minOutputAmount: bigint;
76
+ recipient?: string; // defaults to srcAddress
77
+ deadline?: bigint;
78
+ solver?: Address;
79
+ };
80
+
81
+ // The execute-mode wrapper (createVaultIntent / vaultSwap). The two vault execution modifiers
82
+ // live HERE, never on the generic swap surface:
83
+ type VaultSwapActionParams<K, Raw> = SpokeExecActionParams<K, Raw, CreateIntentParams<K>> & {
84
+ hubWalletSwap?: boolean; // withdraw: inputToken is hub-wallet lsoda*, authorise via Connection.sendMessage
85
+ partnerFee?: PartnerFee; // beats config.swaps.partnerFee for this intent only
86
+ };
87
+ ```
88
+
89
+ ## Common call shapes
90
+
91
+ ### Deposit (any token → `lsoda*`)
92
+
93
+ ```ts
94
+ const built = await sodax.leverageYield.deposit({
95
+ vault: vault.vault,
96
+ srcChainKey: ChainKeys.ARBITRUM_MAINNET,
97
+ srcAddress: '0x…',
98
+ inputToken: '0x…weETHonArbitrum',
99
+ inputAmount: parseUnits('1', 18),
100
+ minOutputAmount: 0n, // quote via sodax.swaps.getQuote (token_dst = vault), then apply slippage
101
+ partnerFee: { address: '0x…', percentage: 100 }, // optional 1% per-intent fee
102
+ });
103
+ if (!built.ok) return;
104
+
105
+ const result = await sodax.leverageYield.vaultSwap({ ...built.value, walletProvider });
106
+ if (!result.ok) return;
107
+ const { solverExecutionResponse, intent, intentDeliveryInfo } = result.value;
108
+ ```
109
+
110
+ ### Withdraw (`lsoda*` → any token)
111
+
112
+ ```ts
113
+ const built = await sodax.leverageYield.withdraw({
114
+ vault: vault.vault,
115
+ srcChainKey: ChainKeys.ARBITRUM_MAINNET, // user signs the sendMessage here
116
+ srcAddress: '0x…',
117
+ dstChainKey: ChainKeys.ARBITRUM_MAINNET, // token delivered here
118
+ outputToken: '0x…weETHonArbitrum',
119
+ inputAmount: shareBalance, // lsoda* to burn
120
+ minOutputAmount: 0n, // quote via sodax.swaps.getQuote (token_src = vault)
121
+ });
122
+ if (!built.ok) return;
123
+ // built.value.hubWalletSwap === true — no spoke approval; the hub wallet authorises the spend
124
+ await sodax.leverageYield.vaultSwap({ ...built.value, walletProvider });
125
+ ```
126
+
127
+ ### Manual create → relay → notify
128
+
129
+ ```ts
130
+ const created = await sodax.leverageYield.createVaultIntent({ ...built.value, raw: false, walletProvider });
131
+ if (!created.ok) return;
132
+ const { tx, relayData } = created.value;
133
+ // relay `tx` with the shared relayTxAndWaitPacket helper using relayData, then:
134
+ await sodax.leverageYield.notifySolver({ intent_tx_hash: hubIntentTxHash });
135
+ ```
136
+
137
+ ## Return shapes
138
+
139
+ | Method | Success type |
140
+ |---|---|
141
+ | `deposit`, `withdraw` | `LeverageYieldSwapPayload` (`{ params: CreateIntentParams; hubWalletSwap?: true; partnerFee? }`) |
142
+ | `createVaultIntent` | `CreateVaultIntentResult<K, Raw>` (`{ tx, intent & feeAmount, relayData }`) |
143
+ | `vaultSwap` | `VaultSwapResponse` (`{ solverExecutionResponse, intent, intentDeliveryInfo }`) |
144
+ | `notifySolver` | `SolverExecutionResponse` (`{ answer, intent_hash }`) |
145
+ | `approve` | `TxReturnType<HubChainKey, R>` |
146
+ | `isAllowanceValid` | `boolean` |
147
+ | `getApr` | `LeverageYieldApr` (`{ supplyAprRay, borrowAprRay, targetLtvBps, leverageMultiplierWad, netAprRay }`, RAY/WAD) |
148
+ | `getEffectiveApr` | `LeverageYieldEffectiveApr` (= `LeverageYieldApr & { lsdApr, effectiveSupplyAprRay, effectiveNetAprRay }`) |
149
+ | `getLsdApr` | `LeverageYieldLsdApr` (`{ aprRay, label, stale }`) |
150
+ | `getPosition` | `LeverageYieldPosition` (`{ collateral, debt, ltv, healthFactor, idleAsset }`) |
151
+ | `getTotalAssets`, `preview*`, `getMaxWithdraw*`, `getShareBalance*` | `bigint` |
152
+ | `getAsset` | `Address` |
153
+ | `listVaults` / `getVault` / `getVaultByAddress` | `LeverageYieldVault[]` / `LeverageYieldVault \| undefined` (synchronous) |
154
+
155
+ ## Error codes
156
+
157
+ `feature: 'leverageYield'`. Action discriminator on `context.action`: `'deposit' | 'withdraw' | 'approve' | 'allowanceCheck' | 'vaultSwap'`. Read methods partition on `context.method`.
158
+
159
+ | Method | Narrow code union |
160
+ |---|---|
161
+ | `deposit`, `withdraw` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| LOOKUP_FAILED \| UNKNOWN` (create-intent subset + `LOOKUP_FAILED` with `method: 'resolveDeadline'` when the default-deadline hub-block read fails) |
162
+ | `createVaultIntent` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| UNKNOWN` (create-intent subset) |
163
+ | `vaultSwap` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` |
164
+ | `notifySolver` | `EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` (with `phase: 'postExecution'`) |
165
+ | `approve` | `VALIDATION_FAILED \| APPROVE_FAILED \| UNKNOWN` |
166
+ | `isAllowanceValid` | `VALIDATION_FAILED \| ALLOWANCE_CHECK_FAILED \| UNKNOWN` (action `'allowanceCheck'`) |
167
+ | Read methods | `VALIDATION_FAILED \| LOOKUP_FAILED \| UNKNOWN` (with `method` discriminator) |
168
+
169
+ Relay/tx-verification codes appear **only** on `vaultSwap` — `createVaultIntent` alone stays within the create-intent subset. `notifySolver` (public, for manual orchestration) emits the post-execution subset, which `vaultSwap` also surfaces.
170
+
171
+ ## Cross-references
172
+
173
+ - ERC-4626 share-as-token model, APR math, and the deliberate swap-domain duplication: SDK source `packages/sdk/docs/LEVERAGE_YIELD.md`.
174
+ - For React Query hooks over this surface, load the `sodax-dapp-kit` skill (integration mode) — its `features/leverage-yield.md`.
175
+ - v2-only feature — no migration sibling.
@@ -8,18 +8,19 @@ Migration of legacy ICON ecosystem tokens to the SODAX hub. Three sub-services:
8
8
 
9
9
  Access: `sodax.migration`. Service class: `MigrationService` (with sub-services `sodax.migration.icxMigration`, `sodax.migration.bnUSDMigrationService`, `sodax.migration.balnSwapService`). Feature tag for errors: `'migration'`.
10
10
 
11
- > 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/icx-bnusd-baln.md`](../../../migration-v1-to-v2/knowledge/features/icx-bnusd-baln.md).
11
+ > 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).
12
12
 
13
13
  ## How it works
14
14
 
15
15
  All three sub-services follow the same pattern: deposit on a spoke chain → relay to hub → execute hub-side migration contract → deliver new token.
16
16
 
17
- `MigrationService` exposes 11 async public methods:
17
+ The `MigrationService` facade exposes 10 async public methods:
18
18
 
19
19
  - 4 orchestrators (full execution): `migratebnUSD`, `migrateIcxToSoda`, `revertMigrateSodaToIcx`, `migrateBaln`.
20
- - 4 intent creators (raw or signed spoke tx, no full lifecycle): `createMigrateBnUSDIntent`, `createMigrateIcxToSodaIntent`, `createRevertMigrateSodaToIcxIntent`, `createMigrateBalnIntent`.
20
+ - 4 intent creators (raw or signed spoke tx, no full lifecycle): `createMigratebnUSDIntent`, `createMigrateIcxToSodaIntent`, `createRevertSodaToIcxMigrationIntent`, `createMigrateBalnIntent`.
21
21
  - `approve`, `isAllowanceValid` (action-discriminated like staking and money market).
22
- - `getAvailableAmount` (read-only; `IcxMigrationService` only — checks how much SODA the user can claim from a partial migration).
22
+
23
+ One more read-only method, `getAvailableAmount`, lives on the `icxMigration` sub-service (not the facade). It reads the migration contract's **total available SODA liquidity** on the hub chain and takes **no arguments** — it is not a per-user "claimable from a partial migration" amount.
23
24
 
24
25
  `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.
25
26
 
@@ -31,11 +32,11 @@ sodax.migration.migrateIcxToSoda<K>(action): Promise<Result<TxHashPair, SodaxErr
31
32
  sodax.migration.revertMigrateSodaToIcx<K>(action): Promise<Result<TxHashPair, SodaxError>>;
32
33
  sodax.migration.migrateBaln<K>(action): Promise<Result<TxHashPair, SodaxError>>;
33
34
 
34
- sodax.migration.createMigrateBnUSDIntent<K, Raw>(...): Promise<Result<...>>;
35
+ sodax.migration.createMigratebnUSDIntent<K, Raw>(...): Promise<Result<...>>;
35
36
  // + 3 other createXxxIntent methods
36
37
 
37
- sodax.migration.approve<K, Raw>(args): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
38
- sodax.migration.isAllowanceValid<K, Raw>(args): Promise<Result<boolean, SodaxError>>;
38
+ sodax.migration.approve<K, Raw>(actionParams, action): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
39
+ sodax.migration.isAllowanceValid<K>(params, action): Promise<Result<boolean, SodaxError>>;
39
40
 
40
41
  sodax.migration.icxMigration.getAvailableAmount(): Promise<Result<bigint, SodaxError>>;
41
42
 
@@ -50,23 +51,47 @@ sodax.migration.balnSwapService.getDetailedUserLocks(...): Promise<DetailedUserL
50
51
 
51
52
  ## Action params shape
52
53
 
54
+ `MigrationParams<K>` is **not** a shared base record — it is a union of the three concrete param types:
55
+
53
56
  ```ts
54
- type MigrationParams<K extends SpokeChainKey> = {
57
+ type MigrationParams<K extends SpokeChainKey> =
58
+ | IcxMigrateParams
59
+ | UnifiedBnUSDMigrateParams<K>
60
+ | BalnMigrateParams;
61
+
62
+ type UnifiedBnUSDMigrateParams<K extends SpokeChainKey> = {
55
63
  srcChainKey: K;
56
- srcAddress: GetAddressType<K>;
64
+ srcAddress: string;
65
+ srcbnUSD: string; // legacy or new bnUSD; SDK detects direction from address
66
+ dstChainKey: SpokeChainKey; // required
67
+ dstbnUSD: string; // the other side
57
68
  amount: bigint;
58
- dstAddress?: string;
69
+ dstAddress: string;
59
70
  };
60
71
 
61
- type UnifiedBnUSDMigrateParams<K> = MigrationParams<K> & {
62
- srcToken: `0x${string}`; // legacy or new bnUSD; SDK detects direction from address
63
- dstToken: `0x${string}`; // the other side
72
+ // ICX and BALN param types are NOT generic over <K>.
73
+ type IcxMigrateParams = {
74
+ srcChainKey: IconChainKey;
75
+ srcAddress: IconAddress;
76
+ address: IcxTokenType; // the ICX or wICX token to migrate (required)
77
+ amount: bigint;
78
+ dstAddress: Address;
64
79
  };
65
80
 
66
- type IcxToSodaMigrateParams<K> = MigrationParams<K>;
67
- type RevertSodaToIcxParams<K> = MigrationParams<K>;
68
- type BalnSwapParams<K> = MigrationParams<K> & {
69
- lockPeriodMonths: 0 | 1 | 2 | 3 | 6 | 12 | 18 | 24; // reward multiplier 0.5x – 1.5x
81
+ type IcxCreateRevertMigrationParams = {
82
+ srcChainKey: SonicChainKey;
83
+ srcAddress: Address;
84
+ amount: bigint;
85
+ dstAddress: IconEoaAddress; // ICON EOA that receives the reverted ICX (required)
86
+ };
87
+
88
+ type BalnMigrateParams = {
89
+ srcChainKey: IconChainKey;
90
+ srcAddress: IconAddress;
91
+ amount: bigint;
92
+ lockupPeriod: LockupPeriod; // enum in SECONDS: NO_LOCKUP | SIX_MONTHS | TWELVE_MONTHS | EIGHTEEN_MONTHS | TWENTY_FOUR_MONTHS (→ 0/6/12/18/24 months)
93
+ dstAddress: Address;
94
+ stake: boolean; // required
70
95
  };
71
96
  ```
72
97
 
@@ -79,8 +104,9 @@ const result = await sodax.migration.migratebnUSD({
79
104
  params: {
80
105
  srcChainKey: ChainKeys.ICON_MAINNET,
81
106
  srcAddress: 'hx…',
82
- srcToken: '0x…', // legacy bnUSD on ICON
83
- dstToken: '0x…', // new bnUSD on BASE
107
+ srcbnUSD: '0x…', // legacy bnUSD on ICON
108
+ dstChainKey: ChainKeys.BASE_MAINNET, // required
109
+ dstbnUSD: '0x…', // new bnUSD on BASE
84
110
  amount: parseUnits('100', 18),
85
111
  dstAddress: '0x…',
86
112
  },
@@ -92,13 +118,19 @@ if (!result.ok) return;
92
118
  const { srcChainTxHash, dstChainTxHash } = result.value;
93
119
  ```
94
120
 
95
- The SDK auto-detects direction from `(srcToken, dstToken)` addresses; the `direction` field surfaces on `error.context` if it fails (`'forward' | 'reverse'`).
121
+ The SDK auto-detects direction from `(srcbnUSD, dstbnUSD)` addresses; the `direction` field surfaces on `error.context` if it fails (`'forward' | 'reverse'`).
96
122
 
97
123
  ### ICX → SODA
98
124
 
99
125
  ```ts
100
126
  await sodax.migration.migrateIcxToSoda({
101
- params: { srcChainKey: ChainKeys.ICON_MAINNET, srcAddress: 'hx…', amount },
127
+ params: {
128
+ srcChainKey: ChainKeys.ICON_MAINNET,
129
+ srcAddress: 'hx…',
130
+ address: icxTokenType, // IcxTokenType — the ICX or wICX token to migrate (required)
131
+ amount,
132
+ dstAddress: '0x…', // required
133
+ },
102
134
  raw: false,
103
135
  walletProvider: iconWp,
104
136
  });
@@ -108,7 +140,12 @@ await sodax.migration.migrateIcxToSoda({
108
140
 
109
141
  ```ts
110
142
  await sodax.migration.revertMigrateSodaToIcx({
111
- params: { srcChainKey: ChainKeys.SONIC_MAINNET, srcAddress: '0x…', amount },
143
+ params: {
144
+ srcChainKey: ChainKeys.SONIC_MAINNET,
145
+ srcAddress: '0x…',
146
+ amount,
147
+ dstAddress: 'hx…', // ICON EOA that receives the reverted ICX (required)
148
+ },
112
149
  raw: false,
113
150
  walletProvider: sonicWp,
114
151
  });
@@ -122,7 +159,9 @@ await sodax.migration.migrateBaln({
122
159
  srcChainKey: ChainKeys.ICON_MAINNET,
123
160
  srcAddress: 'hx…',
124
161
  amount: parseUnits('1000', 18),
125
- lockPeriodMonths: 12, // 1.0x base; 24 is 1.5x; 0 is 0.5x
162
+ lockupPeriod: LockupPeriod.TWELVE_MONTHS, // 1.0x base; TWENTY_FOUR_MONTHS is 1.5x; NO_LOCKUP is 0.5x
163
+ dstAddress: '0x…', // required
164
+ stake: false, // required
126
165
  },
127
166
  raw: false,
128
167
  walletProvider: iconWp,
@@ -131,12 +170,18 @@ await sodax.migration.migrateBaln({
131
170
 
132
171
  ### Approve / allowance — action-discriminated
133
172
 
173
+ `action` is the **second positional argument** (`MigrationAction = 'migrate' | 'revert'`), not a field inside `params`:
174
+
134
175
  ```ts
135
- await sodax.migration.approve({
136
- params: { srcChainKey, srcAddress, amount, action: 'migratebnUSD' /* or 'migrateIcxToSoda' | 'revertMigrateSodaToIcx' | 'migrateBaln' */ },
137
- raw: false,
138
- walletProvider,
139
- });
176
+ // approve takes the action-wrapped params, then the action arg:
177
+ await sodax.migration.approve(
178
+ { params: bnUSDParams, raw: false, walletProvider },
179
+ 'migrate', // or 'revert'
180
+ );
181
+
182
+ // isAllowanceValid takes the BARE migration params (no { params, raw, walletProvider } wrapper,
183
+ // no `raw` flag — it is not Raw-generic) plus the action arg:
184
+ const allowed = await sodax.migration.isAllowanceValid(bnUSDParams, 'migrate');
140
185
  ```
141
186
 
142
187
  ### BALN lock management (carve-out — still throws)
@@ -154,7 +199,7 @@ try {
154
199
  | Method | Success type |
155
200
  |---|---|
156
201
  | 4 orchestrators (`migratebnUSD`, `migrateIcxToSoda`, `revertMigrateSodaToIcx`, `migrateBaln`) | `TxHashPair` |
157
- | 4 intent creators | `CreateIntentResult<K, Raw>` |
202
+ | 4 intent creators | `IntentTxResult<K, Raw>` (`{ tx, relayData }`) |
158
203
  | `approve` | `TxReturnType<K, Raw>` |
159
204
  | `isAllowanceValid` | `boolean` |
160
205
  | `getAvailableAmount` | `bigint` |
@@ -177,5 +222,5 @@ try {
177
222
 
178
223
  ## Cross-references
179
224
 
180
- - v1 → v2 migration of this feature: [`features/icx-bnusd-baln.md`](../../../migration-v1-to-v2/knowledge/features/icx-bnusd-baln.md).
225
+ - v1 → v2 migration of this feature: [`features/migration.md`](../../../migration-v1-to-v2/knowledge/features/migration.md).
181
226
  - Architecture (relay layer's `phase: 'destinationExecution'` for bnUSD): [`../architecture.md`](../architecture.md) § 9.
@@ -1,6 +1,6 @@
1
1
  # Money Market — `MoneyMarketService`
2
2
 
3
- Cross-chain lending and borrowing. Supply, borrow, withdraw, repay across 19 spoke chains. Position state lives on the hub.
3
+ Cross-chain lending and borrowing. Supply, borrow, withdraw, repay across 21 spoke chains. Position state lives on the hub.
4
4
 
5
5
  Access: `sodax.moneyMarket`. Service class: `MoneyMarketService`. Feature tag for errors: `'moneyMarket'`.
6
6
 
@@ -8,7 +8,7 @@ Access: `sodax.moneyMarket`. Service class: `MoneyMarketService`. Feature tag fo
8
8
 
9
9
  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.
10
10
 
11
- 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.
11
+ aTokens (ERC4626 receipt tokens) live on the hub and represent the user's share of each reserve. Use `sodax.moneyMarket.data.getATokenData(aToken)` to fetch their ERC-20 metadata — it returns a plain `Erc20Token` = `{ name, symbol, decimals, address }`.
12
12
 
13
13
  ## Public methods
14
14
 
@@ -44,37 +44,31 @@ sodax.moneyMarket.buildWithdrawData(...): Hex;
44
44
  sodax.moneyMarket.buildRepayData(...): Hex;
45
45
  ```
46
46
 
47
- For per-position user reads (reserves data, user reserves data, formatted summaries, aToken balances, etc.) the entrypoint is `sodax.backendApi`, not `MoneyMarketService` — see `auxiliary-services.md` § "BackendApiService" for `getMoneyMarketPosition`, `getAllMoneyMarketAssets`, `getMoneyMarketAsset`, `getMoneyMarketAssetBorrowers`, `getMoneyMarketAssetSuppliers`, `getAllMoneyMarketBorrowers`.
47
+ For per-reserve and per-user data (reserves data, user reserves data, formatted summaries, aToken balances, etc.) the entrypoint is `sodax.moneyMarket.data` — `getReservesData`, `getUserReservesData`, `getATokensBalances`, `getReservesHumanized`, `getUserReservesHumanized`, `formatUserSummary`. For backend-indexed user position and asset lists use `sodax.backendApi` — see [`backend-api.md`](backend-api.md) for `getMoneyMarketPosition`, `getAllMoneyMarketAssets`, `getMoneyMarketAsset`, `getMoneyMarketAssetBorrowers`, `getMoneyMarketAssetSuppliers`, `getAllMoneyMarketBorrowers`.
48
48
 
49
49
  ## Action params shape
50
50
 
51
- `MoneyMarketParams<K>` is the shared base:
51
+ `MoneyMarketParams<K>` is the **union** of the four action param types. Each is an independent type (NOT an extension of a shared base), and all four carry the same shape — differing only in the `action` literal. Every action (including supply/withdraw) carries optional `dstChainKey?` / `dstAddress?`:
52
52
 
53
53
  ```ts
54
- type MoneyMarketParams<K extends SpokeChainKey> = {
54
+ type MoneyMarketSupplyParams<K extends SpokeChainKey> = {
55
55
  srcChainKey: K;
56
- srcAddress: GetAddressType<K>;
57
- token: `0x${string}`; // hub asset address
56
+ srcAddress: string;
57
+ token: string; // spoke-chain original asset address; hub asset derived internally
58
58
  amount: bigint;
59
- };
60
- ```
61
-
62
- Per-action params:
63
-
64
- ```ts
65
- type MoneyMarketSupplyParams<K> = MoneyMarketParams<K> & { action: 'supply' };
66
- type MoneyMarketWithdrawParams<K> = MoneyMarketParams<K> & { action: 'withdraw' };
67
-
68
- type MoneyMarketBorrowParams<K> = MoneyMarketParams<K> & {
69
- action: 'borrow';
70
- dstChainKey?: SpokeChainKey; // delivery chain; defaults to srcChainKey
71
- dstAddress?: string;
72
- };
73
- type MoneyMarketRepayParams<K> = MoneyMarketParams<K> & {
74
- action: 'repay';
75
- dstChainKey?: SpokeChainKey; // debt chain; defaults to srcChainKey
59
+ action: 'supply';
60
+ dstChainKey?: SpokeChainKey; // delivery/debt chain; defaults to srcChainKey
76
61
  dstAddress?: string;
77
62
  };
63
+ type MoneyMarketBorrowParams<K extends SpokeChainKey> = { /* …same fields… */ action: 'borrow' };
64
+ type MoneyMarketWithdrawParams<K extends SpokeChainKey> = { /* …same fields… */ action: 'withdraw' };
65
+ type MoneyMarketRepayParams<K extends SpokeChainKey> = { /* …same fields… */ action: 'repay' };
66
+
67
+ type MoneyMarketParams<K extends SpokeChainKey> =
68
+ | MoneyMarketSupplyParams<K>
69
+ | MoneyMarketBorrowParams<K>
70
+ | MoneyMarketWithdrawParams<K>
71
+ | MoneyMarketRepayParams<K>;
78
72
  ```
79
73
 
80
74
  ## Common call shapes
@@ -159,7 +153,7 @@ The `action` field routes to the right token under the hood — relevant for rep
159
153
  | Method | Success type |
160
154
  |---|---|
161
155
  | `supply`, `borrow`, `withdraw`, `repay` | `TxHashPair` = `{ srcChainTxHash, dstChainTxHash }` |
162
- | `create*Intent` | `CreateIntentResult<K, Raw>` |
156
+ | `create*Intent` | `IntentTxResult<K, Raw>` = `{ tx, relayData }` |
163
157
  | `approve` | `TxReturnType<K, Raw>` |
164
158
  | `isAllowanceValid` | `boolean` |
165
159
  | `estimateGas` | `GetEstimateGasReturnType<K>` (chain-family-specific) |
@@ -196,3 +190,4 @@ Aave's RAY precision (27 decimals) is used for interest calculations under the h
196
190
  - v1 → v2 money market migration: [`features/money-market.md`](../../../migration-v1-to-v2/knowledge/features/money-market.md).
197
191
  - Architecture (hub-side wallet abstraction, ConfigService): [`../architecture.md`](../architecture.md) §§ 3, 4.
198
192
  - Stellar destinations need a trustline: [`../chain-specifics.md`](../chain-specifics.md).
193
+ - NEAR destinations (borrow/withdraw to NEAR) need NEP-141 storage registration: [`../chain-specifics.md`](../chain-specifics.md).
@@ -0,0 +1,86 @@
1
+ # Partner — `PartnerService`
2
+
3
+ Partner-fee handling. `PartnerService` itself only exposes `feeClaim: PartnerFeeClaimService` and `config: ConfigService` as public fields. Every operation lives on `sodax.partners.feeClaim`.
4
+
5
+ Access: `sodax.partners`. Service class: `PartnerService` (operations on `sodax.partners.feeClaim`). Feature tag for errors: `'partner'`.
6
+
7
+ ## Methods (all on `sodax.partners.feeClaim`)
8
+
9
+ ```ts
10
+ // Token approval
11
+ sodax.partners.feeClaim.isTokenApproved({ srcChainKey, srcAddress, token }): Promise<Result<boolean, Error>>;
12
+ sodax.partners.feeClaim.approveToken<Raw>(args): Promise<Result<TxReturnType, Error>>;
13
+
14
+ // Auto-swap preferences (whether partner-collected fees auto-swap into a target asset)
15
+ sodax.partners.feeClaim.getAutoSwapPreferences(queryAddress): Promise<Result<AutoSwapPreferences, Error>>;
16
+ sodax.partners.feeClaim.setSwapPreference<K, Raw>(args): Promise<Result<TxReturnType, Error>>;
17
+
18
+ // Fee claim flows
19
+ sodax.partners.feeClaim.swap(args): Promise<Result<...>>; // immediate fee swap
20
+ sodax.partners.feeClaim.createIntentAutoSwap<Raw>(args): Promise<Result<...>>; // intent-driven auto-swap
21
+
22
+ // Recover a stuck claim. createIntentAutoSwap() (and swap(), which delegates to it) rejects a
23
+ // same-token claim (output === fee token) up front with VALIDATION_FAILED. The guard fails closed: if
24
+ // the preference lookup it relies on fails, the call returns that error instead of submitting. An
25
+ // already-created same-token intent is unfillable and locks the funds. Cancel via ProtocolIntents' own
26
+ // cancelIntent — the only authorized path: the intent's creator is the ProtocolIntents contract, so the
27
+ // generic SwapService.cancelIntent reverts Unauthorized().
28
+ sodax.partners.feeClaim.cancelIntent<Raw>(args): Promise<Result<TxReturnType, Error>>; // args.params: { srcChainKey: Hub, srcAddress, fromToken, toToken }
29
+
30
+ // Reads
31
+ sodax.partners.feeClaim.fetchAssetsBalances(queryAddress): Promise<Result<...>>;
32
+ sodax.partners.feeClaim.getUserIntent({ user, fromToken, toToken }): Promise<Result<Hex, Error>>; // 0x0…0 = no open intent
33
+ sodax.partners.feeClaim.getIntentDetails(intentHash): Promise<Result<Intent, Error>>;
34
+ sodax.partners.feeClaim.getOriginalAssetAddress(chainId, hubAsset): OriginalAssetAddress | undefined;
35
+ sodax.partners.feeClaim.getSpokeTokenFromOriginalAssetAddress(...): /* … */;
36
+ ```
37
+
38
+ ## Same-token fees (no conversion) — withdraw directly
39
+
40
+ When a partner wants the fee token itself (e.g. claim BTC fees as BTC), there is no swap to do — the
41
+ solver rejects a same-token swap, so `createIntentAutoSwap` (and `swap()`, which delegates to it)
42
+ rejects it up front with `VALIDATION_FAILED` rather than locking the funds in an unfillable intent.
43
+ Instead move the wrapped fee token off Sonic with the bridge:
44
+ `sodax.bridge.bridge({ params: { srcChainKey: Sonic, srcAddress, srcToken: <hub asset on Sonic>,
45
+ amount, dstChainKey: <fee's native chain, or Sonic>, dstToken: <original token on dstChain, or the
46
+ hub asset for same-chain delivery>, recipient } })`. Bridging from Sonic pulls via the partner's
47
+ hub-wallet router, so it needs a bridge allowance — a different spender than the ProtocolIntents
48
+ approval used by the swap claim.
49
+
50
+ ## Common call shape
51
+
52
+ ```ts
53
+ // 1. Check whether the partner's fee token is approved on the hub:
54
+ const approved = await sodax.partners.feeClaim.isTokenApproved({
55
+ srcChainKey: 'sonic', // hub chain key (required by the param type)
56
+ srcAddress: partnerAddress,
57
+ token: '0x…', // hub asset address
58
+ });
59
+
60
+ // 2. Approve once if not:
61
+ if (approved.ok && !approved.value) {
62
+ await sodax.partners.feeClaim.approveToken({
63
+ params: { srcChainKey: 'sonic', srcAddress: partnerAddress, token: '0x…' },
64
+ raw: false,
65
+ walletProvider: sonicWp,
66
+ });
67
+ }
68
+
69
+ // 3. Configure auto-swap preference (one-time):
70
+ await sodax.partners.feeClaim.setSwapPreference({
71
+ params: { /* preference fields */ },
72
+ raw: false,
73
+ walletProvider: sonicWp,
74
+ });
75
+ ```
76
+
77
+ ## Error codes
78
+
79
+ `feature: 'partner'`. Action methods get the full exec set; reads get `LookupErrorCode` partitioned by `error.context.method`.
80
+
81
+ ## Cross-references
82
+
83
+ - v1 → v2 migration of `PartnerService`: [`features/partner.md`](../../../migration-v1-to-v2/knowledge/features/partner.md).
84
+ - Hub-wallet asset recovery (separate service): [`./recovery.md`](recovery.md).
85
+ - Backend HTTP client (separate service): [`./backend-api.md`](backend-api.md).
86
+ - Error model context fields (`error.context.api`, `error.context.method`): [`../reference/`](../reference/) § 3.
@@ -0,0 +1,51 @@
1
+ # Recovery — `RecoveryService`
2
+
3
+ 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).
4
+
5
+ Access: `sodax.recovery`. Service class: `RecoveryService`. Feature tag for errors: `'recovery'`.
6
+
7
+ ## Methods
8
+
9
+ ```ts
10
+ // Read: list non-zero hub-asset balances in a user's hub wallet for one spoke chain
11
+ // (excludes leverage-yield vault share tokens).
12
+ sodax.recovery.fetchHubAssetBalances(args): Promise<Result<HubAssetBalance[], SodaxError>>;
13
+
14
+ // Mutation: withdraw a single hub asset back to a spoke chain.
15
+ // Returns a single chain-specific tx hash (a TxReturnType) when raw: false — not a tx-pair.
16
+ sodax.recovery.withdrawHubAsset<K extends SpokeChainKey, Raw extends boolean>(
17
+ action: WithdrawHubAssetAction<K, Raw>,
18
+ ): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
19
+ ```
20
+
21
+ ## Common call shape
22
+
23
+ ```ts
24
+ // 1. Find what's stuck on the hub for this user:
25
+ const balances = await sodax.recovery.fetchHubAssetBalances({ chainKey, srcAddress });
26
+ if (!balances.ok || balances.value.length === 0) return;
27
+
28
+ // 2. Withdraw one entry back to a spoke chain:
29
+ const result = await sodax.recovery.withdrawHubAsset({
30
+ params: {
31
+ /* token (the spoke-side token address, i.e. spokeTokenAddress), amount, srcChainKey, srcAddress (also the withdrawal destination) */
32
+ },
33
+ raw: false,
34
+ walletProvider: sonicWp,
35
+ });
36
+ ```
37
+
38
+ ## Error codes
39
+
40
+ `feature: 'recovery'`. The mutation method returns the full exec set (including relay codes); the read method returns `LookupErrorCode` partitioned by `error.context.method`.
41
+
42
+ ## When to use
43
+
44
+ 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.
45
+
46
+ ## Cross-references
47
+
48
+ - 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).
49
+ - Partner-fee handling (separate service): [`./partner.md`](partner.md).
50
+ - Backend HTTP client (separate service): [`./backend-api.md`](backend-api.md).
51
+ - Error model context fields: [`../reference/`](../reference/) § 3.