@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,168 @@
1
+ # Recipe: Leverage Yield
2
+
3
+ Leveraged-yield ERC-4626 vaults on Sonic. Deposit any token → `lsoda*` shares, withdraw shares → any token, and read position / APR / TVL / balances.
4
+
5
+ **Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
6
+
7
+ ## Hooks
8
+
9
+ ### Mutations
10
+
11
+ | Hook | Purpose |
12
+ |------|---------|
13
+ | `useLeverageYieldDeposit` | Build a deposit payload (any token → `lsoda*`) |
14
+ | `useLeverageYieldWithdraw` | Build a withdraw payload (`lsoda*` → any token) |
15
+ | `useLeverageYieldVaultSwap` | Execute a built payload end-to-end (create → relay → notify solver) |
16
+ | `useSwapApprove` | Approve the spoke `inputToken` (deposit only — swap-domain hook) |
17
+
18
+ ### Queries
19
+
20
+ | Hook | Purpose |
21
+ |------|---------|
22
+ | `useSwapAllowance` | Check spoke `inputToken` approval (deposit only — swap-domain hook) |
23
+ | `useLeverageYieldEffectiveApr` | AAVE + LSD effective net APR |
24
+ | `useLeverageYieldPosition` | Live position (collateral, debt, LTV, health factor, idle) |
25
+ | `useLeverageYieldTotalAssets` | Vault TVL (18-dp bigint) |
26
+ | `useLeverageYieldPreviewRedeem` | Assets for N shares (pass `1e18` for price-per-share) |
27
+ | `useLeverageYieldShareBalances` | Per-chain share balances (array via `useQueries`) |
28
+
29
+ > A deposit is a swap-style intent, so it approves the **spoke asset manager** via the swap-domain hooks — there is no leverage-yield-specific approve hook. A withdraw carries `hubWalletSwap: true` and needs no spoke approval.
30
+
31
+ ## Vault stats + position
32
+
33
+ ```tsx
34
+ import { useLeverageYieldEffectiveApr, useLeverageYieldTotalAssets, useLeverageYieldPreviewRedeem, useLeverageYieldPosition } from '@sodax/dapp-kit';
35
+ import type { Address } from '@sodax/sdk';
36
+ import { formatUnits } from 'viem';
37
+
38
+ const RAY = 10n ** 27n;
39
+
40
+ function VaultStats({ vault }: { vault: Address }) {
41
+ const { data: apr } = useLeverageYieldEffectiveApr({ params: { vault } }); // 60s refresh
42
+ const { data: tvl } = useLeverageYieldTotalAssets({ params: { vault } }); // 60s refresh
43
+ const { data: position } = useLeverageYieldPosition({ params: { vault } }); // 30s refresh
44
+ const { data: sharePrice } = useLeverageYieldPreviewRedeem({ // 60s refresh
45
+ params: { vault, shares: 10n ** 18n },
46
+ });
47
+
48
+ // RAY (1e27) rates → percent. effectiveNetAprRay folds the LSD staking yield in.
49
+ const netAprPct = apr ? Number((apr.effectiveNetAprRay * 10000n) / RAY) / 100 : undefined;
50
+
51
+ return (
52
+ <div>
53
+ {netAprPct !== undefined && <p>Net APR: {netAprPct.toFixed(2)}%</p>}
54
+ {tvl !== undefined && <p>TVL: {formatUnits(tvl, 18)}</p>}
55
+ {sharePrice !== undefined && <p>1 share = {formatUnits(sharePrice, 18)} assets</p>}
56
+ {position && <p>Health factor: {formatUnits(position.healthFactor, 18)}</p>}
57
+ </div>
58
+ );
59
+ }
60
+ ```
61
+
62
+ ## Share balances across chains
63
+
64
+ `useLeverageYieldShareBalances` returns an **array** — one query per holder. Build `holders` from the chains the user has connected, then aggregate.
65
+
66
+ ```tsx
67
+ import { useLeverageYieldShareBalances } from '@sodax/dapp-kit';
68
+ import type { Address, SpokeChainKey } from '@sodax/sdk';
69
+ import { formatUnits } from 'viem';
70
+
71
+ function ShareTotal({ vault, holders }: { vault: Address; holders: { chainKey: SpokeChainKey; address: string }[] }) {
72
+ const balances = useLeverageYieldShareBalances({ params: { vault, holders } }); // 15s refresh per query
73
+ const total = balances.reduce((acc, q) => acc + (q.data?.shares ?? 0n), 0n);
74
+ return <p>Total shares: {formatUnits(total, 18)}</p>;
75
+ }
76
+ ```
77
+
78
+ ## Deposit (any token → `lsoda*`)
79
+
80
+ Build → approve-if-needed → execute. The built payload is spread straight into `vaultSwap`.
81
+
82
+ ```tsx
83
+ // @ai-snippets-skip — illustrative end-to-end flow wiring the builder, the swap-domain
84
+ // allowance/approve hooks, and the executor across a broad walletProvider union. Real
85
+ // call shapes per hook are in features/leverage-yield.md.
86
+ import { useState } from 'react';
87
+ import {
88
+ useLeverageYieldDeposit, useLeverageYieldVaultSwap, useSwapAllowance, useSwapApprove,
89
+ } from '@sodax/dapp-kit';
90
+ import { useWalletProvider } from '@sodax/wallet-sdk-react';
91
+ import { ChainKeys, type Address, type PartnerFee } from '@sodax/sdk';
92
+ import { parseUnits } from 'viem';
93
+
94
+ const DEPOSIT_PARTNER_FEE: PartnerFee = { address: '0xYourFeeReceiver…', percentage: 100 }; // 1%
95
+
96
+ function DepositForm({ vault, srcAddress, inputToken }: { vault: Address; srcAddress: string; inputToken: string }) {
97
+ const [amount, setAmount] = useState('');
98
+ const chainKey = ChainKeys.ARBITRUM_MAINNET;
99
+ const walletProvider = useWalletProvider({ xChainId: chainKey });
100
+
101
+ const { mutateAsyncSafe: buildDeposit } = useLeverageYieldDeposit();
102
+ const { mutateAsyncSafe: approve } = useSwapApprove();
103
+ const { mutateAsync: vaultSwap, isPending } = useLeverageYieldVaultSwap();
104
+
105
+ const handleDeposit = async () => {
106
+ if (!walletProvider) return;
107
+ const built = await buildDeposit({
108
+ vault, srcChainKey: chainKey, srcAddress, inputToken,
109
+ inputAmount: parseUnits(amount, 18),
110
+ minOutputAmount: 0n, // quote via sodax.swaps.getQuote (token_dst = vault), then subtract slippage
111
+ partnerFee: DEPOSIT_PARTNER_FEE, // per-intent fee — must match the quote's post-fee amount
112
+ });
113
+ if (!built.ok) return;
114
+
115
+ // Deposit approves the spoke asset manager (swap-style). Gate on useSwapAllowance in render.
116
+ await approve({ params: built.value.params, walletProvider });
117
+ await vaultSwap({ ...built.value, walletProvider }); // spread the payload; lsoda* lands in the hub wallet
118
+ };
119
+
120
+ return (
121
+ <div>
122
+ <input value={amount} onChange={(e) => setAmount(e.target.value)} placeholder="amount" />
123
+ <button onClick={handleDeposit} disabled={isPending || !walletProvider}>Deposit</button>
124
+ </div>
125
+ );
126
+ }
127
+ ```
128
+
129
+ ## Withdraw (`lsoda*` → any token)
130
+
131
+ No approval step — `hubWalletSwap: true` authorises the share spend via a `sendMessage`.
132
+
133
+ ```tsx
134
+ // @ai-snippets-skip — illustrative end-to-end flow (builder + executor) across a broad
135
+ // walletProvider union; see features/leverage-yield.md for exact per-hook shapes.
136
+ import { useLeverageYieldWithdraw, useLeverageYieldVaultSwap } from '@sodax/dapp-kit';
137
+ import { useWalletProvider } from '@sodax/wallet-sdk-react';
138
+ import { ChainKeys, type Address } from '@sodax/sdk';
139
+
140
+ function WithdrawButton({ vault, srcAddress, outputToken, shares }: { vault: Address; srcAddress: string; outputToken: string; shares: bigint }) {
141
+ const chainKey = ChainKeys.ARBITRUM_MAINNET;
142
+ const walletProvider = useWalletProvider({ xChainId: chainKey });
143
+ const { mutateAsyncSafe: buildWithdraw } = useLeverageYieldWithdraw();
144
+ const { mutateAsync: vaultSwap, isPending } = useLeverageYieldVaultSwap();
145
+
146
+ const handleWithdraw = async () => {
147
+ if (!walletProvider) return;
148
+ const built = await buildWithdraw({
149
+ vault, srcChainKey: chainKey, srcAddress,
150
+ dstChainKey: chainKey, outputToken,
151
+ inputAmount: shares, // lsoda* shares to burn
152
+ minOutputAmount: 0n, // quote via sodax.swaps.getQuote (token_src = vault), then subtract slippage
153
+ });
154
+ if (!built.ok) return;
155
+ await vaultSwap({ ...built.value, walletProvider }); // built.value.hubWalletSwap === true
156
+ };
157
+
158
+ return <button onClick={handleWithdraw} disabled={isPending || !walletProvider}>Withdraw</button>;
159
+ }
160
+ ```
161
+
162
+ ## Notes
163
+
164
+ - **Two roles:** `deposit` / `withdraw` *build* a `LeverageYieldSwapPayload`; `useLeverageYieldVaultSwap` *executes* it. Always spread the built payload into the executor with a `walletProvider`.
165
+ - **Quotes:** size `minOutputAmount` with `sodax.swaps.getQuote` — vault address as `token_dst` (deposit) or `token_src` (withdraw), since `lsoda*` shares are solver-tradeable. Subtract your slippage tolerance.
166
+ - **Deposit fee:** a per-intent `partnerFee` is deducted from `inputAmount` before the swap; quote on the post-fee amount or the intent won't fill.
167
+ - **Withdraw:** no spoke approval — the hub wallet authorises the share spend via `Connection.sendMessage`. Output lands at `recipient` (defaults to `srcAddress`) on `dstChainKey`.
168
+ - **Reads** (`useLeverageYieldEffectiveApr`, `Position`, `TotalAssets`, `PreviewRedeem`) are already unwrapped — read `data` directly. `useLeverageYieldShareBalances` returns an array; aggregate the `shares` yourself.
@@ -208,5 +208,5 @@ function BnUSDMigration({ srcAddress }: { srcAddress: string }) {
208
208
 
209
209
  - **ICX and BALN forward migrations** don't require approval — ICON has no ERC-20 allowance mechanism.
210
210
  - **SODA → ICX revert** and **EVM/Stellar bnUSD sources** require approval before migrating.
211
- - **BALN lock periods**: `0` = 0.5x reward, `6` = 0.75x, `12` = 1.0x, `24` = 1.5x (months).
211
+ - **BALN lock periods** (months → reward multiplier): `0` = 0.5x, `6` = 0.75x, `12` = 1.0x, `18` = 1.25x, `24` = 1.5x. Pass the `LockupPeriod` enum (whose values are in seconds), not the raw month number.
212
212
  - `useMigratebnUSD` is bidirectional — swap `srcbnUSD`/`dstbnUSD` and `srcChainKey`/`dstChainKey` to go the other direction.
@@ -22,11 +22,11 @@ RPC URLs are injected via `config.chains` — each chain entry takes `{ rpcUrl:
22
22
  // providers.tsx
23
23
  import { QueryClientProvider } from '@tanstack/react-query';
24
24
  import { SodaxProvider, createSodaxQueryClient } from '@sodax/dapp-kit';
25
- import { ChainKeys, type DeepPartial, type SodaxConfig } from '@sodax/sdk';
25
+ import { ChainKeys, type SodaxOptions } from '@sodax/sdk';
26
26
 
27
27
  const queryClient = createSodaxQueryClient();
28
28
 
29
- const sodaxConfig: DeepPartial<SodaxConfig> = {
29
+ const sodaxConfig: SodaxOptions = {
30
30
  chains: {
31
31
  [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://arb1.arbitrum.io/rpc' },
32
32
  [ChainKeys.BASE_MAINNET]: { rpcUrl: 'https://mainnet.base.org' },
@@ -54,7 +54,7 @@ export function Providers({ children }: { children: React.ReactNode }) {
54
54
  ```tsx
55
55
  // @ai-snippets-skip — illustrative; uses placeholder values + JSX without surrounding imports
56
56
  // ✅ Static config — module constant (preferred when nothing depends on runtime state).
57
- const sodaxConfig: DeepPartial<SodaxConfig> = {
57
+ const sodaxConfig: SodaxOptions = {
58
58
  chains: { [ChainKeys.SONIC_MAINNET]: { rpcUrl: '...' } },
59
59
  };
60
60
 
@@ -162,7 +162,7 @@ ChainKeys.INJECTIVE_MAINNET; // 'injective-1'
162
162
  ChainKeys.NEAR_MAINNET; // 'near'
163
163
  ChainKeys.STACKS_MAINNET; // 'stacks'
164
164
  ChainKeys.BITCOIN_MAINNET; // 'bitcoin'
165
- // HyperEVM, Lightlink, Redbelly, Kaia also available.
165
+ // HyperEVM, Lightlink, Redbelly, Kaia, Hedera also available.
166
166
  ```
167
167
 
168
168
  **v1 → v2:** the legacy `*_MAINNET_CHAIN_ID` constants (e.g. `BSC_MAINNET_CHAIN_ID`) are gone. Use `ChainKeys.X_MAINNET` namespace access.
@@ -246,7 +246,7 @@ console.log({ swap, isError, error, swapsInFlight });
246
246
 
247
247
  ### Token list has duplicate addresses
248
248
 
249
- `getSupportedSolverTokens()` can return multiple tokens sharing the same contract address (same token on different chains). When rendering token lists, use a composite key like `${token.address}-${token.blockchain_id}` — not `token.address` alone.
249
+ `sodax.swaps.getSupportedSwapTokens()` returns `Record<SpokeChainKey, readonly XToken[]>`. Flattening it (e.g. `Object.values(...).flat()`) yields multiple tokens sharing the same contract address (same token on different chains). When rendering token lists, use a composite key like `${token.address}-${token.chainKey}` — not `token.address` alone. (`XToken` carries `chainKey`; there is no `blockchain_id` field.)
250
250
 
251
251
  ### Balance display
252
252
 
@@ -16,6 +16,9 @@ Connect wallets and pass wallet providers to feature hooks.
16
16
  | `useEstimateGas` | `@sodax/dapp-kit` | Mutation | Estimate gas for raw transactions |
17
17
  | `useStellarTrustlineCheck` | `@sodax/dapp-kit` | Query | Check if Stellar account has sufficient trustline |
18
18
  | `useRequestTrustline` | `@sodax/dapp-kit` | Mutation | Request a Stellar trustline for a token |
19
+ | `useNearStorageCheck` | `@sodax/dapp-kit` | Query | Check if a NEAR account is NEP-141 storage-registered for a token |
20
+ | `useRegisterNearStorage` | `@sodax/dapp-kit` | Mutation | Submit a NEP-141 `storage_deposit` so a NEAR account can receive a token |
21
+ | `useNearStorageGate` | `@sodax/dapp-kit` | Hook | Combine the NEAR storage check, registration mutation, and UI gate flags |
19
22
 
20
23
  ## Connect a Wallet
21
24
 
@@ -130,7 +130,7 @@ App-level React component. Provides:
130
130
  - RPC config for all chains
131
131
  - Hub provider access (via `useHubProvider()`)
132
132
 
133
- Optional config: `<SodaxProvider config={DeepPartial<SodaxConfig>}>`. Without config, SDK uses packaged defaults.
133
+ Optional config: `<SodaxProvider config={SodaxOptions}>` (`SodaxOptions = DeepPartial<SodaxDefaultConfig> & SodaxOptionalConfig` — the data override plus client-side options `logger` + global `fee`). Without config, SDK uses packaged defaults.
134
134
 
135
135
  Config is tracked by **reference** - see [`recipes/setup.md § Config reactivity`](../recipes/setup.md#config-reactivity) for module-const vs `useMemo` patterns.
136
136
 
@@ -1,6 +1,6 @@
1
1
  # Hooks index — `@sodax/dapp-kit` v2
2
2
 
3
- Comprehensive hook table across 11 feature domains. Use this when you know the feature you're building but don't remember the exact hook name.
3
+ Comprehensive hook table across 12 feature domains. Use this when you know the feature you're building but don't remember the exact hook name.
4
4
 
5
5
  ## Provider + context
6
6
 
@@ -97,6 +97,20 @@ Comprehensive hook table across 11 feature domains. Use this when you know the f
97
97
  | `useCreateSupplyLiquidityParams` | Param builder | Build tick-range + liquidity params |
98
98
  | `useCreateDecreaseLiquidityParams` | Param builder | Build decrease params from position state |
99
99
 
100
+ ## Leverage Yield
101
+
102
+ | Hook | Type | Purpose |
103
+ |---|---|---|
104
+ | `useLeverageYieldDeposit` | Mutation | Build a deposit payload (any token → `lsoda*` shares) — spread into `useLeverageYieldVaultSwap` |
105
+ | `useLeverageYieldWithdraw` | Mutation | Build a withdraw payload (`lsoda*` → any token; `hubWalletSwap`) |
106
+ | `useLeverageYieldVaultSwap` | Mutation | Execute a built payload end-to-end (create → verify → relay → notify solver) |
107
+ | `useLeverageYieldNotifySolver` | Mutation | Manual-flow notify step (after a self-driven `createVaultIntent` + relay) |
108
+ | `useLeverageYieldEffectiveApr` | Query | AAVE + LSD effective net APR (60s) |
109
+ | `useLeverageYieldPosition` | Query | Live position: collateral, debt, LTV, health factor, idle (30s) |
110
+ | `useLeverageYieldTotalAssets` | Query | Vault TVL (18-dp bigint, 60s) |
111
+ | `useLeverageYieldPreviewRedeem` | Query | Assets for N shares; pass `1e18` for price-per-share (60s) |
112
+ | `useLeverageYieldShareBalances` | Query | Per-chain `lsoda*` balances via `useQueries` — returns an array (15s) |
113
+
100
114
  ## Migration
101
115
 
102
116
  | Hook | Type | Purpose |
@@ -108,15 +122,16 @@ Comprehensive hook table across 11 feature domains. Use this when you know the f
108
122
  | `useMigrationApprove` | Mutation | Approve before migration (action-discriminated) |
109
123
  | `useMigrationAllowance` | Query | Approval check (action-discriminated) |
110
124
 
111
- ## Bitcoin / Radfi
125
+ ## Bitcoin / Bound Exchange
112
126
 
113
127
  | Hook | Type | Purpose |
114
128
  |---|---|---|
115
129
  | `useRadfiAuth` | Mutation | Authenticate via BIP322 signing |
130
+ | `useEnsureRadfiAccessToken` | Mutation | Ensure a fresh Bound access token (silent refresh or BIP322 re-auth) |
116
131
  | `useRadfiSession` | Utility | Manage full session lifecycle |
117
132
  | `useTradingWallet` | Utility | Synchronously read trading wallet from localStorage |
118
133
  | `useBitcoinBalance` | Query | BTC balance for any address |
119
- | `useTradingWalletBalance` | Query | Trading wallet balance from Radfi API |
134
+ | `useTradingWalletBalance` | Query | Trading wallet balance from Bound Exchange API |
120
135
  | `useFundTradingWallet` | Mutation | Fund trading wallet from personal wallet |
121
136
  | `useRadfiWithdraw` | Mutation | Withdraw from trading wallet |
122
137
  | `useExpiredUtxos` | Query | Expired UTXOs (polls 60s) |
@@ -132,13 +147,11 @@ Comprehensive hook table across 11 feature domains. Use this when you know the f
132
147
  | `useBackendIntentByHash` | none |
133
148
  | `useBackendUserIntents` | none |
134
149
 
135
- ### Orderbook + swap submission
150
+ ### Orderbook
136
151
 
137
152
  | Hook | Type / Polling |
138
153
  |---|---|
139
154
  | `useBackendOrderbook` | Query; `staleTime: 30s` — fresh-window only, no background refetch |
140
- | `useBackendSubmitSwapTx` | Mutation |
141
- | `useBackendSubmitSwapTxStatus` | Query; polls until `executed` / `failed` |
142
155
 
143
156
  ### Money market data
144
157
 
@@ -151,6 +164,46 @@ Comprehensive hook table across 11 feature domains. Use this when you know the f
151
164
  | `useBackendMoneyMarketAssetBorrowers` | Borrowers for an asset |
152
165
  | `useBackendAllMoneyMarketBorrowers` | All borrowers |
153
166
 
167
+ ## Swaps API (`sodax.api.swaps`)
168
+
169
+ Typed React Query wrappers over the backend Swaps API v2 (`sodax.api.swaps.*`), one per endpoint. Distinct from the on-chain `swap/` hooks (`useQuote`/`useStatus`/`useSwap`/…), which drive `sodax.swaps` (the `SwapService`).
170
+
171
+ ### Tokens · quote · fees · gas (reads)
172
+
173
+ | Hook | Type / Polling |
174
+ |---|---|
175
+ | `useSwapsApiTokens` | Query; all supported swap tokens by chain |
176
+ | `useSwapsApiTokensByChain` | Query; tokens for one chain |
177
+ | `useSwapsApiQuote` | Query; solver quote (set `query.includeTxData` for `txData`) |
178
+ | `useSwapsApiDeadline` | Query; computed swap deadline |
179
+ | `useSwapsApiPartnerFee` | Query; partner fee for an amount |
180
+ | `useSwapsApiSolverFee` | Query; protocol (solver) fee for an amount |
181
+ | `useSwapsApiEstimateGas` | Query; gas estimate for a raw tx |
182
+
183
+ ### Intent lifecycle (reads)
184
+
185
+ | Hook | Type / Polling |
186
+ |---|---|
187
+ | `useSwapsApiAllowance` | Query; `{ valid }` allowance check |
188
+ | `useSwapsApiStatus` | Query (1s); polls until status `3` (SOLVED) / `4` (FAILED) |
189
+ | `useSwapsApiIntentHash` | Query; keccak256 of an intent struct |
190
+ | `useSwapsApiIntentPacket` | Query; long-polls the relayer for the fill packet (no client interval) |
191
+ | `useSwapsApiIntentExtraData` | Query; relay extra-data for submit |
192
+ | `useSwapsApiFilledIntent` | Query; on-chain fill state by tx hash |
193
+ | `useSwapsApiIntent` | Query; decoded intent struct by tx hash |
194
+ | `useSwapsApiSubmitTxStatus` | Query (1s); requires `txHash` + `srcChainKey`; polls until `solved` / `failed` |
195
+
196
+ ### Actions (mutations)
197
+
198
+ | Hook | Type |
199
+ |---|---|
200
+ | `useSwapsApiApprove` | Mutation; builds unsigned approval tx |
201
+ | `useSwapsApiCreateIntent` | Mutation; builds `{ tx, intent, relayData }` |
202
+ | `useSwapsApiSubmitIntent` | Mutation; submits broadcast intent to the relay |
203
+ | `useSwapsApiCancelIntent` | Mutation; builds unsigned cancel tx |
204
+ | `useSwapsApiCreateLimitOrder` | Mutation; builds limit-order intent tx |
205
+ | `useSwapsApiSubmitTx` | Mutation; `request: SubmitTxRequestV2` |
206
+
154
207
  ## Partner
155
208
 
156
209
  | Hook | Type | Purpose |
@@ -158,9 +211,13 @@ Comprehensive hook table across 11 feature domains. Use this when you know the f
158
211
  | `useFetchAssetsBalances` | Query | Fetch partner asset balances |
159
212
  | `useGetAutoSwapPreferences` | Query | Get auto-swap preferences |
160
213
  | `useIsTokenApproved` | Query | Check token approval |
214
+ | `useGetUserIntent` | Query | Look up a partner's stored intent hash for a token pair (`0x0…0` = none) |
215
+ | `useGetIntentDetails` | Query | Read full intent details for an intent hash |
161
216
  | `useApproveToken` | Mutation | Approve token |
162
217
  | `useSetSwapPreference` | Mutation | Set swap preference |
163
218
  | `useFeeClaimSwap` | Mutation | Claim partner fees via swap |
219
+ | `useFeeClaimWithdraw` | Mutation | Withdraw a fee token directly (no swap) via the bridge |
220
+ | `usePartnerCancelIntent` | Mutation | Cancel a stuck same-token claim and recover the locked tokens |
164
221
 
165
222
  ## Recovery
166
223
 
@@ -179,6 +236,10 @@ Comprehensive hook table across 11 feature domains. Use this when you know the f
179
236
  | `useEstimateGas` | Mutation | Estimate gas for raw tx |
180
237
  | `useStellarTrustlineCheck` | Query | Check Stellar trustline |
181
238
  | `useRequestTrustline` | Mutation | Request a Stellar trustline |
239
+ | `useNearStorageCheck` | Query | Check NEP-141 storage registration (NEAR) |
240
+ | `useRegisterNearStorage` | Mutation | Submit NEP-141 `storage_deposit` (NEAR) |
241
+ | `useNearStorageGate` | Hook | Composite NEAR receive-side storage gate |
242
+ | `resolveNearStorageGate` | Utility | Derive gate flags from a `useNearStorageCheck` result (unwrapped) |
182
243
  | `useSafeMutation` | Internal | The wrapper every mutation hook calls |
183
244
  | `unwrapResult` | Internal | `Result<T>` → throw / return |
184
245
  | `toResult` | Internal | `Promise<T>` → `Result<T>` |
@@ -12,6 +12,7 @@ Mandatory shape rules for every `queryKey` and `mutationKey`. Mechanically enfor
12
12
  | `bitcoin/` | `'bitcoin'` |
13
13
  | `bridge/` | `'bridge'` |
14
14
  | `dex/` | `'dex'` |
15
+ | `leverageYield/` | `'leverageYield'` |
15
16
  | `mm/` | `'mm'` |
16
17
  | `partner/` | `'partner'` |
17
18
  | `recovery/` | `'recovery'` |
@@ -77,6 +78,7 @@ queryKey: ['staking', 'allowance', srcChainKey, action, srcAddress, amount.toStr
77
78
  queryKey: ['mm', 'userReservesData', spokeChainKey, userAddress]
78
79
  queryKey: ['staking', 'info', srcChainKey, srcAddress] // useStakingInfo — second segment is 'info', not 'stakingInfo'
79
80
  queryKey: ['shared', 'xBalances', xChainId, tokens, address]
81
+ queryKey: ['shared', 'nearStorageCheck', chainId, token, accountId] // useNearStorageCheck
80
82
 
81
83
  // Mutation default keys
82
84
  mutationKey: ['swap'] // useSwap
@@ -90,6 +92,7 @@ mutationKey: ['staking', 'approve', 'stake'] // useStake
90
92
  mutationKey: ['bridge'] // useBridge — single segment (no 'execute' suffix)
91
93
  mutationKey: ['migrate', 'icxToSoda']
92
94
  mutationKey: ['dex', 'supplyLiquidity']
95
+ mutationKey: ['shared', 'registerNearStorage'] // useRegisterNearStorage
93
96
  ```
94
97
 
95
98
  ## Per-feature key tables
@@ -147,6 +150,52 @@ Skip if you're writing a feature hook for the first time and want to align with
147
150
  | `['staking', 'cancelUnstake']` | `useCancelUnstake` |
148
151
  | `['staking', 'approve', 'stake' \| 'unstake' \| 'instantUnstake']` | `useStakeApprove` / `useUnstakeApprove` / `useInstantUnstakeApprove` |
149
152
 
153
+ ### Backend (read)
154
+
155
+ Backend read hooks (`useBackendIntentByTxHash`, `useBackendIntentByHash`, `useBackendUserIntents`, `useBackendOrderbook`, `useBackendMoneyMarketPosition`, …) follow the `['backend', action, ...]` shape — see the source hook files.
156
+
157
+ ### Swaps API (`sodax.api.swaps`)
158
+
159
+ Typed wrappers over `sodax.api.swaps.*` (one per Swaps API v2 endpoint), all keyed `['swapsApi', action, ...]`.
160
+
161
+ | Key | Hook |
162
+ |---|---|
163
+ | `['swapsApi', 'tokens']` | `useSwapsApiTokens` |
164
+ | `['swapsApi', 'tokens', chainKey]` | `useSwapsApiTokensByChain` |
165
+ | `['swapsApi', 'quote', …]` | `useSwapsApiQuote` |
166
+ | `['swapsApi', 'deadline', …]` | `useSwapsApiDeadline` |
167
+ | `['swapsApi', 'allowance', …]` | `useSwapsApiAllowance` |
168
+ | `['swapsApi', 'status', …]` | `useSwapsApiStatus` |
169
+ | `['swapsApi', 'intentHash', …]` | `useSwapsApiIntentHash` |
170
+ | `['swapsApi', 'intentPacket', …]` | `useSwapsApiIntentPacket` |
171
+ | `['swapsApi', 'intentExtraData', …]` | `useSwapsApiIntentExtraData` |
172
+ | `['swapsApi', 'filledIntent', txHash]` | `useSwapsApiFilledIntent` |
173
+ | `['swapsApi', 'intent', txHash]` | `useSwapsApiIntent` |
174
+ | `['swapsApi', 'estimateGas', …]` | `useSwapsApiEstimateGas` |
175
+ | `['swapsApi', 'partnerFee', amount]` | `useSwapsApiPartnerFee` |
176
+ | `['swapsApi', 'solverFee', amount]` | `useSwapsApiSolverFee` |
177
+ | `['swapsApi', 'submitTx', 'status', txHash, srcChainKey]` | `useSwapsApiSubmitTxStatus` — both identifiers required |
178
+ | `['swapsApi', 'approve']` | `useSwapsApiApprove` mutation |
179
+ | `['swapsApi', 'createIntent']` | `useSwapsApiCreateIntent` mutation |
180
+ | `['swapsApi', 'submitIntent']` | `useSwapsApiSubmitIntent` mutation |
181
+ | `['swapsApi', 'cancelIntent']` | `useSwapsApiCancelIntent` mutation |
182
+ | `['swapsApi', 'createLimitOrder']` | `useSwapsApiCreateLimitOrder` mutation |
183
+ | `['swapsApi', 'submitTx']` | `useSwapsApiSubmitTx` mutation |
184
+
185
+ ### Leverage Yield
186
+
187
+ | Key | Hook |
188
+ |---|---|
189
+ | `['leverageYield', 'effectiveApr', vault]` | `useLeverageYieldEffectiveApr` |
190
+ | `['leverageYield', 'position', vault]` | `useLeverageYieldPosition` |
191
+ | `['leverageYield', 'totalAssets', vault]` | `useLeverageYieldTotalAssets` |
192
+ | `['leverageYield', 'previewRedeem', vault, shares.toString()]` | `useLeverageYieldPreviewRedeem` |
193
+ | `['leverageYield', 'shareBalance', vault, chainKey, address]` | `useLeverageYieldShareBalances` (singular `shareBalance`; one query per holder) |
194
+ | `['leverageYield', 'deposit']` | `useLeverageYieldDeposit` mutation |
195
+ | `['leverageYield', 'withdraw']` | `useLeverageYieldWithdraw` mutation |
196
+ | `['leverageYield', 'vaultSwap']` | `useLeverageYieldVaultSwap` mutation |
197
+ | `['leverageYield', 'notifySolver']` | `useLeverageYieldNotifySolver` mutation |
198
+
150
199
  ### Bridge / DEX / Migration / Bitcoin / etc.
151
200
 
152
201
  Follow the same shape. See the source hook files (`packages/dapp-kit/src/hooks/<feature>/`) for current keys.
@@ -0,0 +1,54 @@
1
+ ---
2
+ name: sodax-dapp-kit-leverage-yield
3
+ description: 'Granular skill for the @sodax/dapp-kit v2 leverage-yield feature only — React Query hooks for leveraged-yield ERC-4626 vaults on Sonic: useLeverageYieldDeposit and useLeverageYieldWithdraw (build a swap payload), useLeverageYieldVaultSwap (execute it end-to-end), plus reads useLeverageYieldEffectiveApr, useLeverageYieldPosition, useLeverageYieldTotalAssets, useLeverageYieldPreviewRedeem, useLeverageYieldShareBalances. Use when a React dapp task is leverage-yield vaults (e.g. "deposit into a leverage vault with dapp-kit", "useLeverageYieldVaultSwap hook", "render vault APR / position / TVL", "lsoda share balances across chains", "withdraw from leverage vault"). New in v2 — integration only, no v1 migration path. Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
8
+ ---
9
+
10
+ # Leverage Yield (dapp-kit granular skill)
11
+
12
+ Granular skill for the leverage-yield hooks of `@sodax/dapp-kit` v2. queryKey/mutationKey first segment: `leverageYield`. React-only — backend uses `@sodax/sdk` directly. **New in v2; no v1 migration path.**
13
+
14
+ ## Step 1 — Clarify with user before coding
15
+
16
+ 1. **Deposit or withdraw?** Deposit = any token → `lsoda*` shares (lands in the hub wallet). Withdraw = `lsoda*` shares → any token on any chain.
17
+ 2. **Build vs execute.** `useLeverageYieldDeposit` / `useLeverageYieldWithdraw` only *build* a `LeverageYieldSwapPayload`; `useLeverageYieldVaultSwap` *executes* it (create → relay → notify solver). You always need both.
18
+ 3. **Approval?** Deposit approves the spoke `inputToken` via the swap-domain `useSwapApprove` / `useSwapAllowance` (no leverage-yield-specific approve hook). Withdraw needs no approval (`hubWalletSwap: true`).
19
+ 4. **Which reads?** `useLeverageYieldEffectiveApr` (headline APR), `useLeverageYieldPosition` (LTV/health), `useLeverageYieldTotalAssets` (TVL), `useLeverageYieldPreviewRedeem` (price-per-share), `useLeverageYieldShareBalances` (per-chain balances — returns an array).
20
+
21
+ ## Integration workflow (new v2 code)
22
+
23
+ 1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
24
+ 2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
25
+ 3. [`../integration/knowledge/features/leverage-yield.md`](../integration/knowledge/features/leverage-yield.md) — full hook surface, mutation TVars, read shapes, approval pattern, gotchas.
26
+ 4. [`../integration/knowledge/recipes/leverage-yield.md`](../integration/knowledge/recipes/leverage-yield.md) — full worked examples (deposit, withdraw, stats, share balances).
27
+ 5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
28
+
29
+ ### Leverage-yield-specific anti-patterns (dapp-kit)
30
+
31
+ - **Calling `useLeverageYieldDeposit` / `useLeverageYieldWithdraw` and expecting a tx.** They are builders — their `data` is a `LeverageYieldSwapPayload`. Spread it into `useLeverageYieldVaultSwap`'s `mutate` with a `walletProvider` to broadcast.
32
+ - **Treating `useLeverageYieldShareBalances` as a single query.** It returns an **array** (one `useQueries` row per holder). Aggregate with `reduce`; the key segment is singular `shareBalance`.
33
+ - **Gating withdraw on an allowance check.** Withdraw carries `hubWalletSwap: true` — the hub wallet authorises the share spend via `sendMessage`. Only `deposit` uses `useSwapAllowance` / `useSwapApprove`.
34
+ - **Reaching for a `useLeverageYieldApprove` hook.** It doesn't exist — the deposit approves the spoke asset manager, so use the swap-domain hooks.
35
+ - **Quoting on the pre-fee amount.** A deposit's per-intent `partnerFee` is deducted from `inputAmount` before the swap — quote on the post-fee amount or `minOutputAmount` is unfillable.
36
+
37
+ ## Verification
38
+
39
+ 1. `pnpm tsc --noEmit` clean.
40
+ 2. Deposit/withdraw build a payload, then `useLeverageYieldVaultSwap` executes it (`{ ...payload, walletProvider }`).
41
+ 3. `useLeverageYieldShareBalances` consumers treat `data` as an array and aggregate.
42
+ 4. Withdraw flows do not gate on `useSwapAllowance`.
43
+ 5. Mutation flows use `mutateAsyncSafe` and branch on `result.ok`; reads read `data` directly (no `.ok`/`.value`).
44
+
45
+ ## Related granular skills (same family)
46
+
47
+ - [`../swap/SKILL.md`](../swap/SKILL.md) — `useSwapApprove` / `useSwapAllowance` (spoke-side deposit approval) and `useQuote` (size `minOutputAmount`) live here.
48
+ - [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — `useXBalances` / gas-estimation utilities used alongside leverage-yield UI.
49
+
50
+ For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
51
+
52
+ ## Wallet connectivity (different SDK package family)
53
+
54
+ `walletProvider` flows through `mutate(vars)`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets and get a typed `walletProvider` via `useWalletProvider({ xChainId: chainKey })`.
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: sodax-dapp-kit-migration
3
+ description: 'Granular skill for the @sodax/dapp-kit v2 token-migration feature only — React Query hooks for migrating legacy ICON-ecosystem tokens to SODAX assets: useMigrateIcxToSoda, useRevertMigrateSodaToIcx, useMigratebnUSD (bidirectional), useMigrateBaln (with lockup), useMigrationApprove/useMigrationAllowance (action-discriminated). Use when a React dapp task is migrating legacy tokens (e.g. "useMigrateIcxToSoda", "migrate bnUSD hook in React", "migrate BALN with lock period hook", "revert SODA to ICX hook"). IMPORTANT — this is the token-protocol migration FEATURE, NOT v1 → v2 SDK code porting (that is the sodax-dapp-kit skill in migration mode). Same word, different concept. Covers BOTH integration (new v2 hooks) and the v1 → v2 port of these migration hooks. Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
8
+ ---
9
+
10
+ # Token migration (dapp-kit granular skill)
11
+
12
+ Granular skill for the token-migration hooks of `@sodax/dapp-kit` v2 — ICX/wICX ↔ SODA, legacy bnUSD ↔ new bnUSD, BALN → SODA. queryKey/mutationKey first segment: `migrate`. React-only — backend uses `@sodax/sdk` directly.
13
+
14
+ > **Important disambiguation.** This skill is about the token-migration **hooks** (migrating legacy ICON tokens to SODAX assets). It is **NOT** about porting v1 dapp-kit code to v2 — that lives under the broad `sodax-dapp-kit` skill (migration mode) and the [`../migration-v1-to-v2/knowledge/`](../migration-v1-to-v2/knowledge/) subtree. Same word, different concept.
15
+
16
+ ## Step 0 — Confirm this IS a token-protocol migration
17
+
18
+ If the user means *"move/send/transfer a token from chain A to B"* → that's a **bridge** (vault-pair, [`../bridge/SKILL.md`](../bridge/SKILL.md)) or a **swap** (solver-routed, [`../swap/SKILL.md`](../swap/SKILL.md)). If they mean *"migrate my v1 dapp-kit code to v2"* → that's the SDK port; load the broad `sodax-dapp-kit` skill in migration mode. Only continue here for legacy ICON-ecosystem token migration.
19
+
20
+ ## Step 1 — Clarify with user before coding
21
+
22
+ 1. **New code or v1 → v2 port (of these hooks)?**
23
+ 2. **Which token?** ICX/wICX → SODA (`useMigrateIcxToSoda`), SODA → wICX revert (`useRevertMigrateSodaToIcx`), legacy bnUSD ↔ new bnUSD (`useMigratebnUSD`, bidirectional), BALN → SODA (`useMigrateBaln`).
24
+ 3. **For BALN: lockup period?** `lockupPeriod` is the `LockupPeriod` enum (values in SECONDS, not months); multiplier ranges 0.5x → 1.5x. `stake: boolean` is REQUIRED.
25
+ 4. **Allowance gating?** ICON-side migrations need none; Sonic-side (revert) and EVM bnUSD do — use `useMigrationAllowance` + `useMigrationApprove` with `action: 'migrate' | 'revert'`.
26
+
27
+ ## Integration workflow (new v2 code)
28
+
29
+ 1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
30
+ 2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
31
+ 3. [`../integration/knowledge/features/migration.md`](../integration/knowledge/features/migration.md) — full hook surface, per-action param types, the `LockupPeriod` enum, action-discriminated approve/allowance.
32
+ 4. [`../integration/knowledge/recipes/migration.md`](../integration/knowledge/recipes/migration.md) — full worked examples.
33
+ 5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
34
+
35
+ ### Token-migration-specific anti-patterns (dapp-kit)
36
+
37
+ - **Passing a literal number for BALN `lockupPeriod`.** Use the `LockupPeriod` enum members; values are seconds, not months. `BalnMigrateParams` also requires `stake: boolean`.
38
+ - **Looking for a second bnUSD hook for the reverse direction.** `useMigratebnUSD` is bidirectional — swap `srcbnUSD`/`dstbnUSD` + chains for the other direction.
39
+ - **Skipping approval on revert / EVM bnUSD.** `useRevertMigrateSodaToIcx` needs SODA approval on Sonic; gate with `useMigrationAllowance` + `useMigrationApprove({ action: 'revert' })`.
40
+ - **Conflating this feature with the SDK v1 → v2 port.** Different concerns; reading one playbook for the other produces broken code.
41
+
42
+ ## Migration workflow (port v1 migration hooks to v2)
43
+
44
+ 1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
45
+ 2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
46
+ 3. [`../migration-v1-to-v2/knowledge/features/migration.md`](../migration-v1-to-v2/knowledge/features/migration.md) — **biggest change**: v1's single `useMigrate(spokeProvider)`-style hook split into the per-action hooks above. The legacy `useMigrate` is in [`../migration-v1-to-v2/knowledge/reference/deleted-hooks.md`](../migration-v1-to-v2/knowledge/reference/deleted-hooks.md).
47
+
48
+ ## Verification
49
+
50
+ 1. `pnpm tsc --noEmit` clean.
51
+ 2. BALN flows pass a `LockupPeriod` enum member and `stake: boolean`.
52
+ 3. Revert / EVM-bnUSD flows gate on `useMigrationAllowance` + `useMigrationApprove`.
53
+ 4. No legacy `useMigrate`, no `useSpokeProvider` (migration only).
54
+
55
+ ## Related granular skills (same family)
56
+
57
+ - [`../staking/SKILL.md`](../staking/SKILL.md) — BALN migration can auto-stake into xSODA (`stake: true`); generic SODA staking lives there.
58
+ - [`../bridge/SKILL.md`](../bridge/SKILL.md), [`../swap/SKILL.md`](../swap/SKILL.md) — for "move a token across chains" (not a token-protocol migration).
59
+
60
+ For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
61
+
62
+ ## Wallet connectivity (different SDK package family)
63
+
64
+ `walletProvider` flows through `mutate(vars)`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets (incl. ICON for ICX/BALN) and get a typed `walletProvider` via `useWalletProvider({ xChainId: chainKey })`.
@@ -27,7 +27,7 @@ The structural shape of every dapp-kit hook changed in v2. Five categories of br
27
27
  + }}>
28
28
  ```
29
29
 
30
- The `config` prop is `DeepPartial<SodaxConfig>` from `@sodax/sdk`. Other fields available: `api`, `solver`, `swaps`, `bridge`, `dex`, `moneyMarket`, `hub`, `relay`, `fee`. See `sodax-sdk`: `migration-v1-to-v2/knowledge/breaking-changes/architecture.md` for the SDK-side reshape.
30
+ The `config` prop is `SodaxOptions` from `@sodax/sdk` (`= DeepPartial<SodaxDefaultConfig> & SodaxOptionalConfig`). Data override fields: `chains`, `api`, `solver`, `swaps`, `bridge`, `dex`, `moneyMarket`, `leverageYield`, `hub`, `relay`. Client-side options (not data fields, never fetched from the backend): the `logger` sink and the global partner `fee` (read back via `sodax.config.fee`). See `sodax-sdk`: `migration-v1-to-v2/knowledge/breaking-changes/architecture.md` for the SDK-side reshape.
31
31
 
32
32
  **Recommended pairing**: replace `new QueryClient()` with `createSodaxQueryClient()` for global mutation observability.
33
33
 
@@ -81,7 +81,7 @@ Full SDK-level detail: `sodax-sdk`: `migration-v1-to-v2/knowledge/breaking-chang
81
81
 
82
82
  ## `SodaxConfig` reshape — `rpcConfig` → `chains`
83
83
 
84
- `SodaxProvider`'s config prop is `DeepPartial<SodaxConfig>`. The SDK renamed/restructured the config:
84
+ `SodaxProvider`'s config prop is `SodaxOptions` (`= DeepPartial<SodaxDefaultConfig> & SodaxOptionalConfig` — the data override plus client-side options `logger` + global `fee`). The SDK renamed/restructured the config:
85
85
 
86
86
  ```diff
87
87
  - <SodaxProvider rpcConfig={{
@@ -131,7 +131,7 @@ If your dapp-kit consumer code catches errors from mutations and uses `instanceo
131
131
  + }
132
132
  ```
133
133
 
134
- `isSodaxError` is re-exported from `@sodax/dapp-kit`. Discriminate via `(error.feature, error.code)` — the feature is now a first-class field, and the code vocabulary is unified to 13 reason-only codes.
134
+ `isSodaxError` is re-exported from `@sodax/dapp-kit`. Discriminate via `(error.feature, error.code)` — the feature is now a first-class field, and the code vocabulary is unified to 14 reason-only codes (`'USER_REJECTED'` is reachable from any orchestrator that wraps a wallet sign step, which lets consumers render a "Cancelled" UI distinct from real failures).
135
135
 
136
136
  Full SDK-level detail: `sodax-sdk`: `migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md`.
137
137
 
@@ -33,7 +33,7 @@ For each feature your app uses, walk the matching `migration/features/<feature>.
33
33
  - [ ] [`features/bridge.md`](features/bridge.md) — bridge.
34
34
  - [ ] [`features/dex.md`](features/dex.md) — deposit / supply liquidity / etc.
35
35
  - [ ] [`features/migration.md`](features/migration.md) — ICX / bnUSD / BALN. **Note:** v1's `useMigrate(spokeProvider)` is gone; v2 has 6 per-action hooks.
36
- - [ ] [`features/bitcoin.md`](features/bitcoin.md) — Radfi.
36
+ - [ ] [`features/bitcoin.md`](features/bitcoin.md) — Bound Exchange.
37
37
  - [ ] [`features/auxiliary-services.md`](features/auxiliary-services.md) — partner, recovery, backend queries, shared utilities.
38
38
 
39
39
  The cross-cutting pattern at every call site:
@@ -10,7 +10,7 @@ Per-feature porting playbooks. Each file shows the v1 → v2 delta for one featu
10
10
  | [`bridge.md`](bridge.md) | Field renames in `useBridge` params (`srcChainId` → `srcChainKey`, `recipient` → `dstAddress`). `useGetBridgeableAmount` shape change. |
11
11
  | [`dex.md`](dex.md) | Two-step flow stayed the same; field renames + `srcChainKey` requirement. `useSupplyLiquidity` mint/increase routing. |
12
12
  | [`migration.md`](migration.md) | **Biggest change**: v1's `useMigrate(spokeProvider)` → 6 per-action hooks. |
13
- | [`bitcoin.md`](bitcoin.md) | Radfi flow shapes are mostly unchanged; provider/session lifecycle hooks tightened. |
13
+ | [`bitcoin.md`](bitcoin.md) | Bound Exchange flow shapes are mostly unchanged; provider/session lifecycle hooks tightened. |
14
14
  | [`auxiliary-services.md`](auxiliary-services.md) | Partner / recovery / backend queries / shared utilities — small per-hook changes. |
15
15
 
16
16
  ## Pair-completeness