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