@sodax/skills 2.0.0-rc.9 → 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 (163) hide show
  1. package/.claude-plugin/plugin.json +1 -9
  2. package/AGENTS.md +119 -14
  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/money-market.md +6 -1
  28. package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
  29. package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
  30. package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
  31. package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
  32. package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md +8 -8
  33. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +168 -0
  34. package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
  35. package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +4 -4
  36. package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
  37. package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md +3 -0
  38. package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md +1 -1
  39. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +67 -6
  40. package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +49 -0
  41. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +54 -0
  42. package/skills/sodax-dapp-kit/migration/SKILL.md +64 -0
  43. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md +1 -1
  44. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +2 -2
  45. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md +1 -1
  46. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md +1 -1
  47. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +19 -10
  48. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md +2 -2
  49. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
  50. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
  51. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +3 -3
  52. package/skills/sodax-dapp-kit/money-market/SKILL.md +61 -0
  53. package/skills/sodax-dapp-kit/staking/SKILL.md +60 -0
  54. package/skills/sodax-dapp-kit/swap/SKILL.md +64 -0
  55. package/skills/sodax-sdk/SKILL.md +11 -6
  56. package/skills/sodax-sdk/backend-api/SKILL.md +21 -15
  57. package/skills/sodax-sdk/bridge/SKILL.md +4 -0
  58. package/skills/sodax-sdk/dex/SKILL.md +5 -1
  59. package/skills/sodax-sdk/integration/knowledge/README.md +1 -1
  60. package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
  61. package/skills/sodax-sdk/integration/knowledge/architecture.md +24 -21
  62. package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
  63. package/skills/sodax-sdk/integration/knowledge/features/README.md +2 -1
  64. package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +27 -16
  65. package/skills/sodax-sdk/integration/knowledge/features/bridge.md +15 -14
  66. package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
  67. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +175 -0
  68. package/skills/sodax-sdk/integration/knowledge/features/migration.md +73 -28
  69. package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
  70. package/skills/sodax-sdk/integration/knowledge/features/partner.md +27 -4
  71. package/skills/sodax-sdk/integration/knowledge/features/recovery.md +5 -4
  72. package/skills/sodax-sdk/integration/knowledge/features/staking.md +2 -2
  73. package/skills/sodax-sdk/integration/knowledge/features/swap.md +42 -24
  74. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
  75. package/skills/sodax-sdk/integration/knowledge/quickstart.md +1 -1
  76. package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -0
  77. package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
  78. package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
  79. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +34 -2
  80. package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +102 -0
  81. package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +28 -4
  82. package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
  83. package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
  84. package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
  85. package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +40 -4
  86. package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +32 -9
  87. package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
  88. package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -4
  89. package/skills/sodax-sdk/leverage-yield/SKILL.md +50 -0
  90. package/skills/sodax-sdk/migration/SKILL.md +5 -1
  91. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
  92. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
  93. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
  94. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +3 -3
  95. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -5
  96. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +1 -1
  97. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +23 -23
  98. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
  99. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
  100. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/migration.md +29 -27
  101. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
  102. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +10 -5
  103. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +2 -2
  104. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +2 -2
  105. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
  106. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +18 -16
  107. package/skills/sodax-sdk/money-market/SKILL.md +7 -3
  108. package/skills/sodax-sdk/partner/SKILL.md +4 -0
  109. package/skills/sodax-sdk/recovery/SKILL.md +5 -1
  110. package/skills/sodax-sdk/staking/SKILL.md +4 -0
  111. package/skills/sodax-sdk/swap/SKILL.md +8 -3
  112. package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
  113. package/skills/sodax-wallet-sdk-core/SKILL.md +7 -3
  114. package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +54 -0
  115. package/skills/sodax-wallet-sdk-core/evm/SKILL.md +54 -0
  116. package/skills/sodax-wallet-sdk-core/icon/SKILL.md +54 -0
  117. package/skills/sodax-wallet-sdk-core/injective/SKILL.md +54 -0
  118. package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
  119. package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +2 -2
  120. package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
  121. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
  122. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
  123. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
  124. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
  125. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
  126. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
  127. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
  128. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
  129. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
  130. package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
  131. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
  132. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
  133. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/testing.md +1 -1
  134. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
  135. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
  136. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
  137. package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
  138. package/skills/sodax-wallet-sdk-core/near/SKILL.md +54 -0
  139. package/skills/sodax-wallet-sdk-core/solana/SKILL.md +54 -0
  140. package/skills/sodax-wallet-sdk-core/stacks/SKILL.md +53 -0
  141. package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +54 -0
  142. package/skills/sodax-wallet-sdk-core/sui/SKILL.md +53 -0
  143. package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
  144. package/skills/sodax-wallet-sdk-react/bridge-to-sdk/SKILL.md +56 -0
  145. package/skills/sodax-wallet-sdk-react/connect/SKILL.md +59 -0
  146. package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
  147. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
  148. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
  149. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +10 -10
  150. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
  151. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +4 -4
  152. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
  153. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
  154. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
  155. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
  156. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
  157. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
  158. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/ssr-setup.md +24 -19
  159. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +1 -1
  160. package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +51 -0
  161. package/skills/sodax-wallet-sdk-react/switch-chain/SKILL.md +51 -0
  162. package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +54 -0
  163. package/skills/sodax-wallet-sdk-react/walletconnect/SKILL.md +52 -0
@@ -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.
@@ -14,12 +14,13 @@ Access: `sodax.migration`. Service class: `MigrationService` (with sub-services
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` |
@@ -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 [`backend-api.md`](backend-api.md) 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).
@@ -8,7 +8,7 @@ Access: `sodax.partners`. Service class: `PartnerService` (operations on `sodax.
8
8
 
9
9
  ```ts
10
10
  // Token approval
11
- sodax.partners.feeClaim.isTokenApproved({ token, srcAddress }): Promise<Result<boolean, Error>>;
11
+ sodax.partners.feeClaim.isTokenApproved({ srcChainKey, srcAddress, token }): Promise<Result<boolean, Error>>;
12
12
  sodax.partners.feeClaim.approveToken<Raw>(args): Promise<Result<TxReturnType, Error>>;
13
13
 
14
14
  // Auto-swap preferences (whether partner-collected fees auto-swap into a target asset)
@@ -19,25 +19,48 @@ sodax.partners.feeClaim.setSwapPreference<K, Raw>(args): Promise<Result<TxReturn
19
19
  sodax.partners.feeClaim.swap(args): Promise<Result<...>>; // immediate fee swap
20
20
  sodax.partners.feeClaim.createIntentAutoSwap<Raw>(args): Promise<Result<...>>; // intent-driven auto-swap
21
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
+
22
30
  // Reads
23
- sodax.partners.feeClaim.fetchAssetsBalances(args): Promise<Result<...>>;
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>>;
24
34
  sodax.partners.feeClaim.getOriginalAssetAddress(chainId, hubAsset): OriginalAssetAddress | undefined;
25
35
  sodax.partners.feeClaim.getSpokeTokenFromOriginalAssetAddress(...): /* … */;
26
36
  ```
27
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
+
28
50
  ## Common call shape
29
51
 
30
52
  ```ts
31
53
  // 1. Check whether the partner's fee token is approved on the hub:
32
54
  const approved = await sodax.partners.feeClaim.isTokenApproved({
33
- token: '0x…', // hub asset address
55
+ srcChainKey: 'sonic', // hub chain key (required by the param type)
34
56
  srcAddress: partnerAddress,
57
+ token: '0x…', // hub asset address
35
58
  });
36
59
 
37
60
  // 2. Approve once if not:
38
61
  if (approved.ok && !approved.value) {
39
62
  await sodax.partners.feeClaim.approveToken({
40
- params: { token: '0x…', amount: 2n ** 256n - 1n },
63
+ params: { srcChainKey: 'sonic', srcAddress: partnerAddress, token: '0x…' },
41
64
  raw: false,
42
65
  walletProvider: sonicWp,
43
66
  });
@@ -7,11 +7,12 @@ Access: `sodax.recovery`. Service class: `RecoveryService`. Feature tag for erro
7
7
  ## Methods
8
8
 
9
9
  ```ts
10
- // Read: list balances of all known hub assets in a user's hub wallet abstraction.
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).
11
12
  sodax.recovery.fetchHubAssetBalances(args): Promise<Result<HubAssetBalance[], SodaxError>>;
12
13
 
13
14
  // Mutation: withdraw a single hub asset back to a spoke chain.
14
- // Returns a tx-pair when raw: false (the hub-side spend + the relayed spoke-side receive).
15
+ // Returns a single chain-specific tx hash (a TxReturnType) when raw: false — not a tx-pair.
15
16
  sodax.recovery.withdrawHubAsset<K extends SpokeChainKey, Raw extends boolean>(
16
17
  action: WithdrawHubAssetAction<K, Raw>,
17
18
  ): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
@@ -21,13 +22,13 @@ sodax.recovery.withdrawHubAsset<K extends SpokeChainKey, Raw extends boolean>(
21
22
 
22
23
  ```ts
23
24
  // 1. Find what's stuck on the hub for this user:
24
- const balances = await sodax.recovery.fetchHubAssetBalances({ /* user / hub-wallet args */ });
25
+ const balances = await sodax.recovery.fetchHubAssetBalances({ chainKey, srcAddress });
25
26
  if (!balances.ok || balances.value.length === 0) return;
26
27
 
27
28
  // 2. Withdraw one entry back to a spoke chain:
28
29
  const result = await sodax.recovery.withdrawHubAsset({
29
30
  params: {
30
- /* hub-asset address, amount, destination spoke chain key, destination address */
31
+ /* token (the spoke-side token address, i.e. spokeTokenAddress), amount, srcChainKey, srcAddress (also the withdrawal destination) */
31
32
  },
32
33
  raw: false,
33
34
  walletProvider: sonicWp,
@@ -7,7 +7,7 @@ Access: `sodax.staking`. Service class: `StakingService`. Feature tag for errors
7
7
  ## How it works
8
8
 
9
9
  - **SODA** (the staked asset) → **xSoda** (ERC4626 vault shares, proportional to current exchange rate).
10
- - **Unstake** has a configurable waiting period with linear penalty (max 1–100%).
10
+ - **Unstake** has a configurable waiting period with a piecewise penalty (max 1–100%): the flat `maxPenalty` applies during the minimum period, then decays linearly to zero by the full unstaking period, and is none after.
11
11
  - **Instant unstake** bypasses the waiting period but pays slippage (via `StakingRouter`).
12
12
  - **Claim** redeems SODA after the unstaking period expires.
13
13
  - **Cancel unstake** restores xSoda from a pending unstake request before claim.
@@ -140,7 +140,7 @@ const allowed = await sodax.staking.isAllowanceValid({
140
140
  | `create*Intent` | `CreateIntentResult<K, Raw>` |
141
141
  | `approve` | `TxReturnType<K, Raw>` |
142
142
  | `isAllowanceValid` | `boolean` |
143
- | `getStakingConfig` | `{ unstakingPeriod, maxPenalty, minPenalty, /* … */ }` |
143
+ | `getStakingConfig` | `{ unstakingPeriod, minUnstakingPeriod, maxPenalty }` |
144
144
  | `getStakeRatio` | `[xSodaAmount: bigint, previewDepositAmount: bigint]` (estimated xSoda shares + vault's `previewDeposit` preview) |
145
145
  | `getInstantUnstakeRatio` | `bigint` |
146
146
  | `getConvertedAssets` | `bigint` (SODA per xSoda) |