@sodax/skills 2.0.0-rc.8 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -0
- package/AGENTS.md +123 -13
- package/README.md +5 -2
- package/package.json +1 -1
- package/skills/sodax-build/SKILL.md +90 -0
- package/skills/sodax-build/knowledge/README.md +35 -0
- package/skills/sodax-build/knowledge/brief-template.md +41 -0
- package/skills/sodax-build/knowledge/chains-and-assets.md +26 -0
- package/skills/sodax-build/knowledge/example-sessions.md +84 -0
- package/skills/sodax-build/knowledge/feature-catalog.md +51 -0
- package/skills/sodax-build/knowledge/glossary.md +35 -0
- package/skills/sodax-build/knowledge/handoff.md +60 -0
- package/skills/sodax-build/knowledge/interview-guide.md +66 -0
- package/skills/sodax-build/knowledge/monetization.md +37 -0
- package/skills/sodax-build/knowledge/use-case-gallery.md +32 -0
- package/skills/sodax-dapp-kit/SKILL.md +6 -2
- package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +65 -0
- package/skills/sodax-dapp-kit/bitcoin/SKILL.md +57 -0
- package/skills/sodax-dapp-kit/bridge/SKILL.md +59 -0
- package/skills/sodax-dapp-kit/dex/SKILL.md +60 -0
- package/skills/sodax-dapp-kit/integration/knowledge/README.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/README.md +3 -2
- package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +71 -11
- package/skills/sodax-dapp-kit/integration/knowledge/features/bitcoin.md +10 -6
- package/skills/sodax-dapp-kit/integration/knowledge/features/dex.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +112 -0
- package/skills/sodax-dapp-kit/integration/knowledge/features/migration.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +6 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md +8 -8
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +168 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +4 -4
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md +3 -0
- package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +67 -6
- package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +49 -0
- package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +54 -0
- package/skills/sodax-dapp-kit/migration/SKILL.md +64 -0
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +2 -2
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +19 -10
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md +2 -2
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/migration.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +3 -3
- package/skills/sodax-dapp-kit/money-market/SKILL.md +61 -0
- package/skills/sodax-dapp-kit/staking/SKILL.md +60 -0
- package/skills/sodax-dapp-kit/swap/SKILL.md +64 -0
- package/skills/sodax-sdk/SKILL.md +54 -50
- package/skills/sodax-sdk/backend-api/SKILL.md +58 -0
- package/skills/sodax-sdk/bridge/SKILL.md +53 -0
- package/skills/sodax-sdk/dex/SKILL.md +54 -0
- package/skills/sodax-sdk/integration/knowledge/README.md +5 -3
- package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/architecture.md +26 -39
- package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
- package/skills/sodax-sdk/integration/knowledge/features/README.md +6 -3
- package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +92 -0
- package/skills/sodax-sdk/integration/knowledge/features/bridge.md +48 -11
- package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
- package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +175 -0
- package/skills/sodax-sdk/integration/knowledge/features/{icx-bnusd-baln.md → migration.md} +75 -30
- package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
- package/skills/sodax-sdk/integration/knowledge/features/partner.md +86 -0
- package/skills/sodax-sdk/integration/knowledge/features/recovery.md +51 -0
- package/skills/sodax-sdk/integration/knowledge/features/staking.md +8 -3
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +106 -22
- package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
- package/skills/sodax-sdk/integration/knowledge/quickstart.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -0
- package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
- package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +34 -2
- package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +102 -0
- package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +28 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
- package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +40 -4
- package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +32 -9
- package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
- package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -4
- package/skills/sodax-sdk/leverage-yield/SKILL.md +50 -0
- package/skills/sodax-sdk/migration/SKILL.md +69 -0
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +6 -10
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +3 -3
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -5
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/README.md +4 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +92 -0
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/{icx-bnusd-baln.md → migration.md} +31 -29
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +64 -0
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +35 -0
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +8 -3
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +19 -17
- package/skills/sodax-sdk/money-market/SKILL.md +56 -0
- package/skills/sodax-sdk/partner/SKILL.md +55 -0
- package/skills/sodax-sdk/recovery/SKILL.md +53 -0
- package/skills/sodax-sdk/staking/SKILL.md +53 -0
- package/skills/sodax-sdk/swap/SKILL.md +72 -0
- package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
- package/skills/sodax-wallet-sdk-core/SKILL.md +7 -3
- package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/evm/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/icon/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/injective/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/testing.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
- package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/near/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/solana/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/stacks/SKILL.md +53 -0
- package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/sui/SKILL.md +53 -0
- package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
- package/skills/sodax-wallet-sdk-react/bridge-to-sdk/SKILL.md +56 -0
- package/skills/sodax-wallet-sdk-react/connect/SKILL.md +59 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +10 -10
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +4 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/ssr-setup.md +24 -19
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +1 -1
- package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +51 -0
- package/skills/sodax-wallet-sdk-react/switch-chain/SKILL.md +51 -0
- package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-react/walletconnect/SKILL.md +52 -0
- package/skills/sodax-sdk/integration/knowledge/features/auxiliary-services.md +0 -189
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/auxiliary-services.md +0 -156
|
@@ -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
|
|
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
|
|
25
|
+
import { ChainKeys, type SodaxOptions } from '@sodax/sdk';
|
|
26
26
|
|
|
27
27
|
const queryClient = createSodaxQueryClient();
|
|
28
28
|
|
|
29
|
-
const 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:
|
|
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
|
-
`
|
|
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<
|
|
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
|
|
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 /
|
|
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
|
|
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
|
|
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 })`.
|
package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md
CHANGED
|
@@ -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 `
|
|
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<
|
|
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
|
|
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) —
|
|
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) |
|
|
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
|