@sodax/skills 2.0.0-rc.12 → 2.0.0-rc.13

package/.claude-plugin/plugin.json

@@ -7,6 +7,7 @@
     "./skills/sodax-sdk/bridge",
     "./skills/sodax-sdk/staking",
     "./skills/sodax-sdk/dex",
+    "./skills/sodax-sdk/leverage-yield",
     "./skills/sodax-sdk/migration",
     "./skills/sodax-sdk/partner",
     "./skills/sodax-sdk/recovery",
@@ -34,6 +35,7 @@
     "./skills/sodax-dapp-kit/staking",
     "./skills/sodax-dapp-kit/bridge",
     "./skills/sodax-dapp-kit/dex",
+    "./skills/sodax-dapp-kit/leverage-yield",
     "./skills/sodax-dapp-kit/migration",
     "./skills/sodax-dapp-kit/bitcoin",
     "./skills/sodax-dapp-kit/auxiliary-services"

package/AGENTS.md

@@ -8,10 +8,10 @@ This package ships **four mode-gated broad skills** (`skills/<name>/SKILL.md`)
 
 | SDK package | Broad skill | Granular per-feature skills |
 |---|---|---|
-| `@sodax/sdk` | `sodax-sdk` | `sodax-sdk/swap`, `sodax-sdk/money-market`, `sodax-sdk/bridge`, `sodax-sdk/staking`, `sodax-sdk/dex`, `sodax-sdk/migration`, `sodax-sdk/partner`, `sodax-sdk/recovery`, `sodax-sdk/backend-api` |
+| `@sodax/sdk` | `sodax-sdk` | `sodax-sdk/swap`, `sodax-sdk/money-market`, `sodax-sdk/bridge`, `sodax-sdk/staking`, `sodax-sdk/dex`, `sodax-sdk/leverage-yield`, `sodax-sdk/migration`, `sodax-sdk/partner`, `sodax-sdk/recovery`, `sodax-sdk/backend-api` |
 | `@sodax/wallet-sdk-core` | `sodax-wallet-sdk-core` | `sodax-wallet-sdk-core/evm`, `sodax-wallet-sdk-core/solana`, `sodax-wallet-sdk-core/sui`, `sodax-wallet-sdk-core/bitcoin`, `sodax-wallet-sdk-core/stellar`, `sodax-wallet-sdk-core/icon`, `sodax-wallet-sdk-core/injective`, `sodax-wallet-sdk-core/near`, `sodax-wallet-sdk-core/stacks` |
 | `@sodax/wallet-sdk-react` | `sodax-wallet-sdk-react` | `sodax-wallet-sdk-react/connect`, `sodax-wallet-sdk-react/wallet-modal`, `sodax-wallet-sdk-react/bridge-to-sdk`, `sodax-wallet-sdk-react/switch-chain`, `sodax-wallet-sdk-react/sign-message`, `sodax-wallet-sdk-react/walletconnect` |
-| `@sodax/dapp-kit` | `sodax-dapp-kit` | `sodax-dapp-kit/swap`, `sodax-dapp-kit/money-market`, `sodax-dapp-kit/staking`, `sodax-dapp-kit/bridge`, `sodax-dapp-kit/dex`, `sodax-dapp-kit/migration`, `sodax-dapp-kit/bitcoin`, `sodax-dapp-kit/auxiliary-services` |
+| `@sodax/dapp-kit` | `sodax-dapp-kit` | `sodax-dapp-kit/swap`, `sodax-dapp-kit/money-market`, `sodax-dapp-kit/staking`, `sodax-dapp-kit/bridge`, `sodax-dapp-kit/dex`, `sodax-dapp-kit/leverage-yield`, `sodax-dapp-kit/migration`, `sodax-dapp-kit/bitcoin`, `sodax-dapp-kit/auxiliary-services` |
 
 **When to prefer a granular skill:** if the consumer has already picked a sub-domain (e.g. *"swap with Sodax"*, *"supply on money market"*, *"useSwap hook"*, *"instantiate EvmWalletProvider"*, *"add a connect button"*), load the matching granular skill — it's ~3 KB vs the broad skill's ~13 KB and points at exactly the knowledge files needed. For a React dapp that has settled on one feature, load `sodax-dapp-kit/<feature>`; for raw SDK / backend work, load `sodax-sdk/<feature>`; for a known chain in a backend/Node wallet flow, load `sodax-wallet-sdk-core/<chain>`; for a known React wallet concern (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect), load `sodax-wallet-sdk-react/<concern>`. Load the broad skill when the sub-domain is undecided, the task spans several, or the consumer is porting a full v1 codebase.
 
@@ -23,8 +23,8 @@ Pick the consumer's situation, load the listed skills in order. Each entry names
 
 | Consumer is… | Load skills (mode) |
 |---|---|
-| **Scaffolding ONE specific Core SDK feature** (swap, money-market, bridge, staking, dex, migration, partner, recovery, backend-api) | `sodax-sdk/<feature>` (granular, covers both modes via internal links). Add `sodax-wallet-sdk-core` (integration) if it signs and lives outside React. Skip the broad `sodax-sdk` skill |
-| **Scaffolding ONE specific dapp-kit feature in React** (swap, money-market, staking, bridge, dex, migration, bitcoin, auxiliary-services) | `sodax-wallet-sdk-react` (integration) → `sodax-dapp-kit/<feature>` (granular, covers both modes via internal links). Skip the broad `sodax-dapp-kit` skill. If the wallet concern is also settled (just a connect button, modal, bridge, etc.), narrow to `sodax-wallet-sdk-react/<concern>` too |
+| **Scaffolding ONE specific Core SDK feature** (swap, money-market, bridge, staking, dex, leverage-yield, migration, partner, recovery, backend-api) | `sodax-sdk/<feature>` (granular, covers both modes via internal links). Add `sodax-wallet-sdk-core` (integration) if it signs and lives outside React. Skip the broad `sodax-sdk` skill |
+| **Scaffolding ONE specific dapp-kit feature in React** (swap, money-market, staking, bridge, dex, leverage-yield, migration, bitcoin, auxiliary-services) | `sodax-wallet-sdk-react` (integration) → `sodax-dapp-kit/<feature>` (granular, covers both modes via internal links). Skip the broad `sodax-dapp-kit` skill. If the wallet concern is also settled (just a connect button, modal, bridge, etc.), narrow to `sodax-wallet-sdk-react/<concern>` too |
 | **Scaffolding ONE chain's wallet provider** (backend/Node/non-React: evm, solana, sui, bitcoin, stellar, icon, injective, near, stacks) | `sodax-wallet-sdk-core/<chain>` (granular, covers both modes) → `sodax-sdk/<feature>` for the operation it signs. Skip the broad `sodax-wallet-sdk-core` skill |
 | **Scaffolding ONE React wallet concern** (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect) | `sodax-wallet-sdk-react/<concern>` (granular, covers both modes). Skip the broad `sodax-wallet-sdk-react` skill |
 | **Building a NEW React dapp** | `sodax-wallet-sdk-react` (integration) → `sodax-dapp-kit` (integration) → (`sodax-sdk` (integration) only if dropping below dapp-kit) |
@@ -58,8 +58,8 @@ packages/skills/
 ├── .claude-plugin/plugin.json             # Skill registry (broad + nested granular paths)
 └── skills/                                # Each broad skill is mode-gated; some have nested granular children
     ├── sodax-sdk/                         {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
-    │                                       <feature>/SKILL.md ×9 — swap, money-market, bridge, staking, dex,
-    │                                       migration, partner, recovery, backend-api}
+    │                                       <feature>/SKILL.md ×10 — swap, money-market, bridge, staking, dex,
+    │                                       leverage-yield, migration, partner, recovery, backend-api}
     ├── sodax-wallet-sdk-core/             {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
     │                                       <chain>/SKILL.md ×9 — evm, solana, sui, bitcoin, stellar, icon,
     │                                       injective, near, stacks}
@@ -68,8 +68,8 @@ packages/skills/
     │                                       <concern>/SKILL.md ×6 — connect, wallet-modal, bridge-to-sdk,
     │                                       switch-chain, sign-message, walletconnect}
     └── sodax-dapp-kit/                    {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
-                                            <feature>/SKILL.md ×8 — swap, money-market, staking, bridge, dex,
-                                            migration, bitcoin, auxiliary-services}
+                                            <feature>/SKILL.md ×9 — swap, money-market, staking, bridge, dex,
+                                            leverage-yield, migration, bitcoin, auxiliary-services}
 ```
 
 Each `<mode>/knowledge/` subtree contains `ai-rules.md`, `quickstart.md`, `architecture.md`, `features/`, `recipes/`, `reference/`, and `chain-specifics.md` / `breaking-changes/` where applicable.

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "2.0.0-rc.12",
+  "version": "2.0.0-rc.13",
   "license": "MIT",
   "description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
   "keywords": [

package/skills/sodax-dapp-kit/integration/knowledge/features/README.md

@@ -9,6 +9,7 @@ Per-feature reference docs. Each file documents the hooks, params types, return
 | [`staking.md`](staking.md) | SODA → xSODA staking: `useStake`, `useUnstake`, `useInstantUnstake`, `useClaim`, `useCancelUnstake`, allowance/approve, info/ratio reads. |
 | [`bridge.md`](bridge.md) | Cross-chain token bridging: `useBridge`, allowance/approve, bridgeable amount/tokens. |
 | [`dex.md`](dex.md) | Concentrated liquidity DEX: assets in/out, liquidity supply/decrease, claim rewards, position info, pool reads, param builders. |
+| [`leverage-yield.md`](leverage-yield.md) | Leveraged-yield ERC-4626 vaults: `useLeverageYieldDeposit`/`Withdraw` (build) + `useLeverageYieldVaultSwap` (execute), effective APR / position / TVL / share-balance reads. |
 | [`migration.md`](migration.md) | Token migration: `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln`, allowance/approve. |
 | [`bitcoin.md`](bitcoin.md) | Bound Exchange (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
 | [`auxiliary-services.md`](auxiliary-services.md) | Partner fee claiming, recovery, backend queries (intent tracking, orderbook, MM data), shared utilities (xBalances, gas, trustlines). |
@@ -20,7 +21,7 @@ Per-feature reference docs. Each file documents the hooks, params types, return
 
 ## Pair-completeness
 
-Every file in this directory has a sibling in [`features/`](../../../migration-v1-to-v2/knowledge/features/) with the same filename — the v1→v2 porting playbook for that feature. When you're deep in one, the other is one path-swap away.
+Every file in this directory has a sibling in [`features/`](../../../migration-v1-to-v2/knowledge/features/) with the same filename — the v1→v2 porting playbook for that feature. When you're deep in one, the other is one path-swap away. **Exception:** features introduced in v2 with no v1 equivalent (`leverage-yield.md`) have no migration sibling — there is nothing to port.
 
 ## Cross-references
 

package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md

@@ -0,0 +1,112 @@
+# Leverage Yield — `@sodax/dapp-kit`
+
+Leveraged-yield ERC-4626 vaults on the Sonic hub. Deposit any token → `lsoda*` vault shares, withdraw shares → any token; plus position / APR / TVL / share-balance reads. New in v2 (no v1 equivalent).
+
+## Hook surface
+
+```ts
+// @ai-snippets-skip
+// Mutations
+useLeverageYieldDeposit({ mutationOptions });   // build a deposit payload (any token → lsoda*)
+useLeverageYieldWithdraw({ mutationOptions });  // build a withdraw payload (lsoda* → any token; hubWalletSwap)
+useLeverageYieldVaultSwap({ mutationOptions });  // EXECUTE the built payload end-to-end
+useLeverageYieldNotifySolver({ mutationOptions }); // manual-flow: notify the solver after a self-driven relay
+
+// Reads
+useLeverageYieldEffectiveApr({ params, queryOptions });  // AAVE + LSD effective net APR (60s)
+useLeverageYieldPosition({ params, queryOptions });      // collateral/debt/ltv/healthFactor/idle (30s)
+useLeverageYieldTotalAssets({ params, queryOptions });   // vault TVL, 18-dp bigint (60s)
+useLeverageYieldPreviewRedeem({ params, queryOptions }); // assets for N shares; price-per-share (60s)
+useLeverageYieldShareBalances({ params, queryOptions }); // per-chain share balances via useQueries (15s)
+```
+
+`deposit` / `withdraw` are **builders** — they assemble a `LeverageYieldSwapPayload`, they do NOT broadcast. Spread the built payload into `useLeverageYieldVaultSwap`'s `mutate`, adding the `walletProvider`. There is no dedicated leverage-yield approve hook: the swap-style deposit approves the spoke-side asset manager, so reuse `useSwapApprove` / `useSwapAllowance` (see Approval pattern).
+
+## Mutation TVars
+
+```ts
+// @ai-snippets-skip
+// deposit — vars are the SDK's deposit params (any token → lsoda* on the hub wallet)
+type UseLeverageYieldDepositVars = LeverageYieldSwapDepositParams;
+//   { vault: Address; srcChainKey; srcAddress; inputToken; inputAmount: bigint;
+//     minOutputAmount: bigint; deadline?: bigint; solver?: Address; partnerFee? }
+
+// withdraw — lsoda* shares → any token on any chain (hub-wallet sourced)
+type UseLeverageYieldWithdrawVars = LeverageYieldSwapWithdrawParams;
+//   { vault: Address; srcChainKey; srcAddress; dstChainKey; outputToken;
+//     inputAmount: bigint; minOutputAmount: bigint; recipient?; deadline?; solver? }
+
+// vaultSwap — the executor. Spread the built payload + walletProvider.
+type UseLeverageYieldVaultSwapVars<K> = Omit<VaultSwapActionParams<K, false>, 'raw'>;
+//   = SpokeExecActionParams<K, false, CreateIntentParams<K>> & { hubWalletSwap?; partnerFee? }
+//   i.e. { params: CreateIntentParams<K>; walletProvider; hubWalletSwap?; partnerFee?; timeout? }
+
+// notifySolver — manual-flow notify step (vaultSwap already notifies internally)
+type UseLeverageYieldNotifySolverVars = SolverExecutionRequest;
+//   { intent_tx_hash: Hex }  — the hub-side tx hash where the intent landed
+```
+
+## Read shapes (key picks)
+
+```ts
+// @ai-snippets-skip
+// useLeverageYieldEffectiveApr — AAVE rates + LSD staking yield, leverage re-applied (data unwrapped)
+useLeverageYieldEffectiveApr({ params: { vault } })
+//   → UseQueryResult<LeverageYieldEffectiveApr>
+//   LeverageYieldEffectiveApr = LeverageYieldApr & { lsdApr, effectiveSupplyAprRay, effectiveNetAprRay }
+//   LeverageYieldApr = { supplyAprRay, borrowAprRay, targetLtvBps, leverageMultiplierWad, netAprRay } (RAY = 1e27)
+
+// useLeverageYieldPosition — live position snapshot
+useLeverageYieldPosition({ params: { vault } })
+//   → UseQueryResult<LeverageYieldPosition>
+//   LeverageYieldPosition = { collateral, debt, ltv, healthFactor, idleAsset } (all bigint)
+
+// useLeverageYieldPreviewRedeem — assets per shares; pass 1e18 for price-per-share
+useLeverageYieldPreviewRedeem({ params: { vault, shares: 10n ** 18n } })
+//   → UseQueryResult<bigint>
+
+// useLeverageYieldShareBalances — returns an ARRAY (one query per holder), NOT a single result
+useLeverageYieldShareBalances({ params: { vault, holders } })
+//   → UseQueryResult<LeverageYieldShareHolding>[]
+//   LeverageYieldShareHolding = { chainKey: SpokeChainKey; holder: Address; shares: bigint }
+//   holders: { chainKey: SpokeChainKey; address: string }[]  — one row per chain the user may hold under
+```
+
+## Approval pattern
+
+Leverage-yield has **no dedicated approve hook**. A deposit is a swap-style intent that bridges `inputToken` from the spoke chain, so it approves the spoke-side asset manager exactly like a swap — reuse the swap hooks. A withdraw needs no spoke-side approval: the payload carries `hubWalletSwap: true` and `vaultSwap` authorises the hub wallet to spend the `lsoda*` shares via a `Connection.sendMessage` the user signs on `srcChainKey`.
+
+| Flow | Token approved | Hook |
+|---|---|---|
+| `deposit` | spoke `inputToken` → asset manager | `useSwapApprove`, `useSwapAllowance` (swap domain) |
+| `withdraw` | none (hub-wallet `sendMessage` authorises the spend) | — |
+
+## Return shapes
+
+All read hooks here are **already unwrapped** — they throw on SDK `!ok` so `isError` / `error` / `retry` engage. Read `data` directly; do NOT branch on `data.ok`.
+
+| Hook | Returns |
+|---|---|
+| `useLeverageYieldDeposit` / `useLeverageYieldWithdraw` | `SafeUseMutationResult<LeverageYieldSwapPayload, Error, …>` (builder — `data` is the payload to spread into `useLeverageYieldVaultSwap`) |
+| `useLeverageYieldVaultSwap` | `SafeUseMutationResult<VaultSwapResponse, Error, …>` (`{ solverExecutionResponse, intent, intentDeliveryInfo }`) |
+| `useLeverageYieldNotifySolver` | `SafeUseMutationResult<SolverExecutionResponse, Error, …>` (`{ answer: 'OK', intent_hash }`) |
+| `useLeverageYieldEffectiveApr` | `UseQueryResult<LeverageYieldEffectiveApr, Error>` |
+| `useLeverageYieldPosition` | `UseQueryResult<LeverageYieldPosition, Error>` |
+| `useLeverageYieldTotalAssets` | `UseQueryResult<bigint, Error>` |
+| `useLeverageYieldPreviewRedeem` | `UseQueryResult<bigint, Error>` |
+| `useLeverageYieldShareBalances` | `UseQueryResult<LeverageYieldShareHolding, Error>[]` (array — one entry per holder) |
+
+## Gotchas
+
+1. **`deposit` / `withdraw` are builders, not executors.** Their `data` is a `LeverageYieldSwapPayload` — spread it into `useLeverageYieldVaultSwap`'s `mutate` with a `walletProvider` to actually run the swap. Calling them does not broadcast anything.
+2. **`useLeverageYieldShareBalances` returns an ARRAY, not a single query.** It fans out one `useQueries` row per holder. Aggregate yourself: `balances.reduce((acc, q) => acc + (q.data?.shares ?? 0n), 0n)`. `queryOptions` is spread into every per-holder query (no top-level options slot on `useQueries`).
+3. **The share-balance key segment is singular: `shareBalance`** (`['leverageYield', 'shareBalance', vault, chainKey, address]`) — one per holder, even though the hook name is plural.
+4. **Withdraw needs no spoke approval.** Don't gate it on `useSwapAllowance` — the hub-wallet `sendMessage` path approves the share spend internally. Only `deposit` needs the swap-domain allowance/approve pair.
+5. **Deposit's per-intent `partnerFee` must be reflected in the quote.** If you charge a deposit-only fee (e.g. 1%), `vaultSwap`'s underlying `createVaultIntent` deducts it from `inputAmount` before the swap — quote on the post-fee amount, or `minOutputAmount` becomes unfillable and the intent never settles.
+6. **`useLeverageYieldVaultSwap` invalidates xBalances on both chains** (`['shared', 'xBalances', srcChainKey]` and `dstChainKey`) on success. Compose your own `onSuccess` after the hook's — it runs first.
+7. **`useLeverageYieldNotifySolver` is for the manual flow only.** `useLeverageYieldVaultSwap` already notifies the solver internally — only reach for the standalone notify hook when you built the intent with `sodax.leverageYield.createVaultIntent` and relayed it yourself. It does NOT invalidate any queries: its only var is `{ intent_tx_hash }` (no chain context), and the fill lands asynchronously afterward.
+
+## Cross-references
+
+- [`../recipes/leverage-yield.md`](../recipes/leverage-yield.md) — full worked deposit / withdraw / reads examples.
+- For the underlying SDK leverage-yield surface (`LeverageYieldService`, `createVaultIntent`, `notifySolver`, APR math), load the `sodax-sdk` skill (integration mode) — its `features/leverage-yield.md`.

package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md

@@ -35,6 +35,7 @@ Copy-paste patterns for adding SODAX features to a React app. Each recipe is sel
 | [`staking.md`](staking.md) | `useStake`, `useUnstake`, `useClaim`, staking info, ratios |
 | [`migration.md`](migration.md) | `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln` |
 | [`dex.md`](dex.md) | `useDexDeposit`, `useSupplyLiquidity`, positions, pools |
+| [`leverage-yield.md`](leverage-yield.md) | `useLeverageYieldDeposit`, `useLeverageYieldWithdraw`, `useLeverageYieldVaultSwap`, APR/position/TVL/share-balance reads |
 | [`bitcoin.md`](bitcoin.md) | `useRadfiSession`, `useFundTradingWallet`, `useRadfiWithdraw`, UTXO management |
 | [`backend-queries.md`](backend-queries.md) | Intent tracking, orderbook, money market position queries (read-only, no wallet) |
 

package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md

@@ -0,0 +1,168 @@
+# Recipe: Leverage Yield
+
+Leveraged-yield ERC-4626 vaults on Sonic. Deposit any token → `lsoda*` shares, withdraw shares → any token, and read position / APR / TVL / balances.
+
+**Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
+
+## Hooks
+
+### Mutations
+
+| Hook | Purpose |
+|------|---------|
+| `useLeverageYieldDeposit` | Build a deposit payload (any token → `lsoda*`) |
+| `useLeverageYieldWithdraw` | Build a withdraw payload (`lsoda*` → any token) |
+| `useLeverageYieldVaultSwap` | Execute a built payload end-to-end (create → relay → notify solver) |
+| `useSwapApprove` | Approve the spoke `inputToken` (deposit only — swap-domain hook) |
+
+### Queries
+
+| Hook | Purpose |
+|------|---------|
+| `useSwapAllowance` | Check spoke `inputToken` approval (deposit only — swap-domain hook) |
+| `useLeverageYieldEffectiveApr` | AAVE + LSD effective net APR |
+| `useLeverageYieldPosition` | Live position (collateral, debt, LTV, health factor, idle) |
+| `useLeverageYieldTotalAssets` | Vault TVL (18-dp bigint) |
+| `useLeverageYieldPreviewRedeem` | Assets for N shares (pass `1e18` for price-per-share) |
+| `useLeverageYieldShareBalances` | Per-chain share balances (array via `useQueries`) |
+
+> 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.
+
+## Vault stats + position
+
+```tsx
+import { useLeverageYieldEffectiveApr, useLeverageYieldTotalAssets, useLeverageYieldPreviewRedeem, useLeverageYieldPosition } from '@sodax/dapp-kit';
+import type { Address } from '@sodax/sdk';
+import { formatUnits } from 'viem';
+
+const RAY = 10n ** 27n;
+
+function VaultStats({ vault }: { vault: Address }) {
+  const { data: apr } = useLeverageYieldEffectiveApr({ params: { vault } });       // 60s refresh
+  const { data: tvl } = useLeverageYieldTotalAssets({ params: { vault } });        // 60s refresh
+  const { data: position } = useLeverageYieldPosition({ params: { vault } });      // 30s refresh
+  const { data: sharePrice } = useLeverageYieldPreviewRedeem({                     // 60s refresh
+    params: { vault, shares: 10n ** 18n },
+  });
+
+  // RAY (1e27) rates → percent. effectiveNetAprRay folds the LSD staking yield in.
+  const netAprPct = apr ? Number((apr.effectiveNetAprRay * 10000n) / RAY) / 100 : undefined;
+
+  return (
+    <div>
+      {netAprPct !== undefined && <p>Net APR: {netAprPct.toFixed(2)}%</p>}
+      {tvl !== undefined && <p>TVL: {formatUnits(tvl, 18)}</p>}
+      {sharePrice !== undefined && <p>1 share = {formatUnits(sharePrice, 18)} assets</p>}
+      {position && <p>Health factor: {formatUnits(position.healthFactor, 18)}</p>}
+    </div>
+  );
+}
+```
+
+## Share balances across chains
+
+`useLeverageYieldShareBalances` returns an **array** — one query per holder. Build `holders` from the chains the user has connected, then aggregate.
+
+```tsx
+import { useLeverageYieldShareBalances } from '@sodax/dapp-kit';
+import type { Address, SpokeChainKey } from '@sodax/sdk';
+import { formatUnits } from 'viem';
+
+function ShareTotal({ vault, holders }: { vault: Address; holders: { chainKey: SpokeChainKey; address: string }[] }) {
+  const balances = useLeverageYieldShareBalances({ params: { vault, holders } }); // 15s refresh per query
+  const total = balances.reduce((acc, q) => acc + (q.data?.shares ?? 0n), 0n);
+  return <p>Total shares: {formatUnits(total, 18)}</p>;
+}
+```
+
+## Deposit (any token → `lsoda*`)
+
+Build → approve-if-needed → execute. The built payload is spread straight into `vaultSwap`.
+
+```tsx
+// @ai-snippets-skip — illustrative end-to-end flow wiring the builder, the swap-domain
+// allowance/approve hooks, and the executor across a broad walletProvider union. Real
+// call shapes per hook are in features/leverage-yield.md.
+import { useState } from 'react';
+import {
+  useLeverageYieldDeposit, useLeverageYieldVaultSwap, useSwapAllowance, useSwapApprove,
+} from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys, type Address, type PartnerFee } from '@sodax/sdk';
+import { parseUnits } from 'viem';
+
+const DEPOSIT_PARTNER_FEE: PartnerFee = { address: '0xYourFeeReceiver…', percentage: 100 }; // 1%
+
+function DepositForm({ vault, srcAddress, inputToken }: { vault: Address; srcAddress: string; inputToken: string }) {
+  const [amount, setAmount] = useState('');
+  const chainKey = ChainKeys.ARBITRUM_MAINNET;
+  const walletProvider = useWalletProvider({ xChainId: chainKey });
+
+  const { mutateAsyncSafe: buildDeposit } = useLeverageYieldDeposit();
+  const { mutateAsyncSafe: approve } = useSwapApprove();
+  const { mutateAsync: vaultSwap, isPending } = useLeverageYieldVaultSwap();
+
+  const handleDeposit = async () => {
+    if (!walletProvider) return;
+    const built = await buildDeposit({
+      vault, srcChainKey: chainKey, srcAddress, inputToken,
+      inputAmount: parseUnits(amount, 18),
+      minOutputAmount: 0n,             // quote via sodax.swaps.getQuote (token_dst = vault), then subtract slippage
+      partnerFee: DEPOSIT_PARTNER_FEE, // per-intent fee — must match the quote's post-fee amount
+    });
+    if (!built.ok) return;
+
+    // Deposit approves the spoke asset manager (swap-style). Gate on useSwapAllowance in render.
+    await approve({ params: built.value.params, walletProvider });
+    await vaultSwap({ ...built.value, walletProvider }); // spread the payload; lsoda* lands in the hub wallet
+  };
+
+  return (
+    <div>
+      <input value={amount} onChange={(e) => setAmount(e.target.value)} placeholder="amount" />
+      <button onClick={handleDeposit} disabled={isPending || !walletProvider}>Deposit</button>
+    </div>
+  );
+}
+```
+
+## Withdraw (`lsoda*` → any token)
+
+No approval step — `hubWalletSwap: true` authorises the share spend via a `sendMessage`.
+
+```tsx
+// @ai-snippets-skip — illustrative end-to-end flow (builder + executor) across a broad
+// walletProvider union; see features/leverage-yield.md for exact per-hook shapes.
+import { useLeverageYieldWithdraw, useLeverageYieldVaultSwap } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys, type Address } from '@sodax/sdk';
+
+function WithdrawButton({ vault, srcAddress, outputToken, shares }: { vault: Address; srcAddress: string; outputToken: string; shares: bigint }) {
+  const chainKey = ChainKeys.ARBITRUM_MAINNET;
+  const walletProvider = useWalletProvider({ xChainId: chainKey });
+  const { mutateAsyncSafe: buildWithdraw } = useLeverageYieldWithdraw();
+  const { mutateAsync: vaultSwap, isPending } = useLeverageYieldVaultSwap();
+
+  const handleWithdraw = async () => {
+    if (!walletProvider) return;
+    const built = await buildWithdraw({
+      vault, srcChainKey: chainKey, srcAddress,
+      dstChainKey: chainKey, outputToken,
+      inputAmount: shares,         // lsoda* shares to burn
+      minOutputAmount: 0n,         // quote via sodax.swaps.getQuote (token_src = vault), then subtract slippage
+    });
+    if (!built.ok) return;
+    await vaultSwap({ ...built.value, walletProvider }); // built.value.hubWalletSwap === true
+  };
+
+  return <button onClick={handleWithdraw} disabled={isPending || !walletProvider}>Withdraw</button>;
+}
+```
+
+## Notes
+
+- **Two roles:** `deposit` / `withdraw` *build* a `LeverageYieldSwapPayload`; `useLeverageYieldVaultSwap` *executes* it. Always spread the built payload into the executor with a `walletProvider`.
+- **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.
+- **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.
+- **Withdraw:** no spoke approval — the hub wallet authorises the share spend via `Connection.sendMessage`. Output lands at `recipient` (defaults to `srcAddress`) on `dstChainKey`.
+- **Reads** (`useLeverageYieldEffectiveApr`, `Position`, `TotalAssets`, `PreviewRedeem`) are already unwrapped — read `data` directly. `useLeverageYieldShareBalances` returns an array; aggregate the `shares` yourself.

package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md

@@ -1,6 +1,6 @@
 # Hooks index — `@sodax/dapp-kit` v2
 
-Comprehensive hook table across 11 feature domains. Use this when you know the feature you're building but don't remember the exact hook name.
+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.
 
 ## Provider + context
 
@@ -97,6 +97,20 @@ Comprehensive hook table across 11 feature domains. Use this when you know the f
 | `useCreateSupplyLiquidityParams` | Param builder | Build tick-range + liquidity params |
 | `useCreateDecreaseLiquidityParams` | Param builder | Build decrease params from position state |
 
+## Leverage Yield
+
+| Hook | Type | Purpose |
+|---|---|---|
+| `useLeverageYieldDeposit` | Mutation | Build a deposit payload (any token → `lsoda*` shares) — spread into `useLeverageYieldVaultSwap` |
+| `useLeverageYieldWithdraw` | Mutation | Build a withdraw payload (`lsoda*` → any token; `hubWalletSwap`) |
+| `useLeverageYieldVaultSwap` | Mutation | Execute a built payload end-to-end (create → verify → relay → notify solver) |
+| `useLeverageYieldNotifySolver` | Mutation | Manual-flow notify step (after a self-driven `createVaultIntent` + relay) |
+| `useLeverageYieldEffectiveApr` | Query | AAVE + LSD effective net APR (60s) |
+| `useLeverageYieldPosition` | Query | Live position: collateral, debt, LTV, health factor, idle (30s) |
+| `useLeverageYieldTotalAssets` | Query | Vault TVL (18-dp bigint, 60s) |
+| `useLeverageYieldPreviewRedeem` | Query | Assets for N shares; pass `1e18` for price-per-share (60s) |
+| `useLeverageYieldShareBalances` | Query | Per-chain `lsoda*` balances via `useQueries` — returns an array (15s) |
+
 ## Migration
 
 | Hook | Type | Purpose |

package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md

@@ -12,6 +12,7 @@ Mandatory shape rules for every `queryKey` and `mutationKey`. Mechanically enfor
 | `bitcoin/` | `'bitcoin'` |
 | `bridge/` | `'bridge'` |
 | `dex/` | `'dex'` |
+| `leverageYield/` | `'leverageYield'` |
 | `mm/` | `'mm'` |
 | `partner/` | `'partner'` |
 | `recovery/` | `'recovery'` |
@@ -149,6 +150,20 @@ Skip if you're writing a feature hook for the first time and want to align with
 | `['staking', 'cancelUnstake']` | `useCancelUnstake` |
 | `['staking', 'approve', 'stake' \| 'unstake' \| 'instantUnstake']` | `useStakeApprove` / `useUnstakeApprove` / `useInstantUnstakeApprove` |
 
+### Leverage Yield
+
+| Key | Hook |
+|---|---|
+| `['leverageYield', 'effectiveApr', vault]` | `useLeverageYieldEffectiveApr` |
+| `['leverageYield', 'position', vault]` | `useLeverageYieldPosition` |
+| `['leverageYield', 'totalAssets', vault]` | `useLeverageYieldTotalAssets` |
+| `['leverageYield', 'previewRedeem', vault, shares.toString()]` | `useLeverageYieldPreviewRedeem` |
+| `['leverageYield', 'shareBalance', vault, chainKey, address]` | `useLeverageYieldShareBalances` (singular `shareBalance`; one query per holder) |
+| `['leverageYield', 'deposit']` | `useLeverageYieldDeposit` mutation |
+| `['leverageYield', 'withdraw']` | `useLeverageYieldWithdraw` mutation |
+| `['leverageYield', 'vaultSwap']` | `useLeverageYieldVaultSwap` mutation |
+| `['leverageYield', 'notifySolver']` | `useLeverageYieldNotifySolver` mutation |
+
 ### Bridge / DEX / Migration / Bitcoin / etc.
 
 Follow the same shape. See the source hook files (`packages/dapp-kit/src/hooks/<feature>/`) for current keys.

package/skills/sodax-dapp-kit/leverage-yield/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: sodax-dapp-kit-leverage-yield
+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.'
+---
+
+# Leverage Yield (dapp-kit granular skill)
+
+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.**
+
+## Step 1 — Clarify with user before coding
+
+1. **Deposit or withdraw?** Deposit = any token → `lsoda*` shares (lands in the hub wallet). Withdraw = `lsoda*` shares → any token on any chain.
+2. **Build vs execute.** `useLeverageYieldDeposit` / `useLeverageYieldWithdraw` only *build* a `LeverageYieldSwapPayload`; `useLeverageYieldVaultSwap` *executes* it (create → relay → notify solver). You always need both.
+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`).
+4. **Which reads?** `useLeverageYieldEffectiveApr` (headline APR), `useLeverageYieldPosition` (LTV/health), `useLeverageYieldTotalAssets` (TVL), `useLeverageYieldPreviewRedeem` (price-per-share), `useLeverageYieldShareBalances` (per-chain balances — returns an array).
+
+## Integration workflow (new v2 code)
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
+3. [`../integration/knowledge/features/leverage-yield.md`](../integration/knowledge/features/leverage-yield.md) — full hook surface, mutation TVars, read shapes, approval pattern, gotchas.
+4. [`../integration/knowledge/recipes/leverage-yield.md`](../integration/knowledge/recipes/leverage-yield.md) — full worked examples (deposit, withdraw, stats, share balances).
+5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
+
+### Leverage-yield-specific anti-patterns (dapp-kit)
+
+- **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.
+- **Treating `useLeverageYieldShareBalances` as a single query.** It returns an **array** (one `useQueries` row per holder). Aggregate with `reduce`; the key segment is singular `shareBalance`.
+- **Gating withdraw on an allowance check.** Withdraw carries `hubWalletSwap: true` — the hub wallet authorises the share spend via `sendMessage`. Only `deposit` uses `useSwapAllowance` / `useSwapApprove`.
+- **Reaching for a `useLeverageYieldApprove` hook.** It doesn't exist — the deposit approves the spoke asset manager, so use the swap-domain hooks.
+- **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.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Deposit/withdraw build a payload, then `useLeverageYieldVaultSwap` executes it (`{ ...payload, walletProvider }`).
+3. `useLeverageYieldShareBalances` consumers treat `data` as an array and aggregate.
+4. Withdraw flows do not gate on `useSwapAllowance`.
+5. Mutation flows use `mutateAsyncSafe` and branch on `result.ok`; reads read `data` directly (no `.ok`/`.value`).
+
+## Related granular skills (same family)
+
+- [`../swap/SKILL.md`](../swap/SKILL.md) — `useSwapApprove` / `useSwapAllowance` (spoke-side deposit approval) and `useQuote` (size `minOutputAmount`) live here.
+- [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — `useXBalances` / gas-estimation utilities used alongside leverage-yield UI.
+
+For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
+
+## Wallet connectivity (different SDK package family)
+
+`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 })`.

package/skills/sodax-sdk/integration/knowledge/features/README.md

@@ -9,6 +9,7 @@ One file per feature service. Each file documents the v2 API surface, common cal
 | [`staking.md`](staking.md) | `StakingService` | SODA → xSoda staking via ERC-4626 vault. Stake, unstake (with penalty curve), instant unstake (slippage), claim, cancel. |
 | [`bridge.md`](bridge.md) | `BridgeService` | Cross-chain token transfer via vault. `bridge` returns `TxHashPair = { srcChainTxHash, dstChainTxHash }`. Bridgeable-amount queries respect vault deposit limits. |
 | [`dex.md`](dex.md) | `ClService` + `AssetService` | Uniswap-V3-style concentrated liquidity positions. Asset deposit/withdraw. Increase/decrease/claim flows. |
+| [`leverage-yield.md`](leverage-yield.md) | `LeverageYieldService` | Leveraged-yield ERC-4626 vaults on Sonic. Deposit/withdraw as solver-tradeable `lsoda*` swaps; effective APR (AAVE + LSD), position, share-balance reads. |
 | [`migration.md`](migration.md) | `MigrationService` (the SDK module — not v1→v2 porting) | Legacy ICON ecosystem token migration. ICX ↔ SODA, legacy bnUSD ↔ new bnUSD, BALN → SODA with lockup multipliers. |
 | [`partner.md`](partner.md) | `PartnerService` | Partner-fee handling: token approval, auto-swap preferences, fee-claim flows. |
 | [`recovery.md`](recovery.md) | `RecoveryService` | Withdraw stuck hub-wallet assets back to a spoke chain. |
@@ -18,4 +19,4 @@ All feature services are constructed and wired by the `Sodax` facade. You don't
 
 ## Cross-references to migration
 
-For the v1 → v2 port playbook on each feature, see the matching file in [`features/`](../../../migration-v1-to-v2/knowledge/features/) — same filename, different angle.
+For the v1 → v2 port playbook on each feature, see the matching file in [`features/`](../../../migration-v1-to-v2/knowledge/features/) — same filename, different angle. **Exception:** features introduced in v2 with no v1 equivalent (`leverage-yield.md`) have no migration sibling — there is nothing to port.

package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md

@@ -0,0 +1,175 @@
+# Leverage Yield — `LeverageYieldService`
+
+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.
+
+Access: `sodax.leverageYield`. Service class: `LeverageYieldService`. Feature tag for errors: `'leverageYield'`.
+
+## How it works
+
+- 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`.
+- The ERC-4626 **share token is the vault proxy address itself** (`lsoda*`). Holding shares = holding the leveraged position.
+- **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.
+- **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.
+
+## Public methods
+
+```ts
+// Builders — assemble a LeverageYieldSwapPayload (spread into vaultSwap). Do NOT broadcast.
+sodax.leverageYield.deposit(params: LeverageYieldSwapDepositParams): Promise<Result<LeverageYieldSwapPayload, SodaxError>>;
+sodax.leverageYield.withdraw(params: LeverageYieldSwapWithdrawParams): Promise<Result<LeverageYieldSwapPayload, SodaxError>>;
+//   withdraw sets hubWalletSwap: true; both default `deadline` from the hub block timestamp (so withdraw is async)
+
+// Intent create + end-to-end execute (leverage-yield copies of swap's createIntent / swap)
+sodax.leverageYield.createVaultIntent<K, Raw>(params: VaultSwapActionParams<K, Raw>): Promise<Result<CreateVaultIntentResult<K, Raw>, SodaxError>>;
+sodax.leverageYield.vaultSwap<K>(params: VaultSwapActionParams<K, false>): Promise<Result<VaultSwapResponse, SodaxError>>;
+sodax.leverageYield.notifySolver(request: { intent_tx_hash: string }): Promise<Result<SolverExecutionResponse, SodaxError>>;
+//   notifySolver is PUBLIC — call it to finish a manual createVaultIntent → relay → notify flow
+
+// Sonic-direct allowance for the vault's underlying asset (the swap-style deposit handles its own approvals)
+sodax.leverageYield.approve<R>(params: LeverageYieldApproveParams<R>): Promise<Result<TxReturnType<HubChainKey, R>, SodaxError>>;
+sodax.leverageYield.isAllowanceValid(params: LeverageYieldAllowanceParams): Promise<Result<boolean, SodaxError>>;
+
+// Reads (all Result<…, SodaxError> with LOOKUP_FAILED on failure)
+sodax.leverageYield.getApr(vault): Promise<Result<LeverageYieldApr, SodaxError>>;             // AAVE-only steady-state
+sodax.leverageYield.getEffectiveApr(vault): Promise<Result<LeverageYieldEffectiveApr, SodaxError>>; // + LSD staking yield (headline)
+sodax.leverageYield.getLsdApr(vault): Promise<Result<LeverageYieldLsdApr, SodaxError>>;       // off-chain DefiLlama; always ok for a known vault
+sodax.leverageYield.getPosition(vault): Promise<Result<LeverageYieldPosition, SodaxError>>;
+sodax.leverageYield.getTotalAssets(vault): Promise<Result<bigint, SodaxError>>;              // TVL
+sodax.leverageYield.previewDeposit(vault, assets): Promise<Result<bigint, SodaxError>>;
+sodax.leverageYield.previewWithdraw(vault, assets): Promise<Result<bigint, SodaxError>>;
+sodax.leverageYield.previewRedeem(vault, shares): Promise<Result<bigint, SodaxError>>;
+sodax.leverageYield.getMaxWithdraw(vault, owner): Promise<Result<bigint, SodaxError>>;
+sodax.leverageYield.getMaxWithdrawForUser(vault, srcChainKey, srcAddress): Promise<Result<bigint, SodaxError>>; // dust-buffered
+sodax.leverageYield.getShareBalance(vault, owner): Promise<Result<bigint, SodaxError>>;
+sodax.leverageYield.getShareBalanceForUser(vault, srcChainKey, srcAddress): Promise<Result<bigint, SodaxError>>;
+sodax.leverageYield.getAsset(vault): Promise<Result<Address, SodaxError>>;
+
+// Registry (synchronous)
+sodax.leverageYield.listVaults(): readonly LeverageYieldVault[];
+sodax.leverageYield.getVault(name): LeverageYieldVault | undefined;
+sodax.leverageYield.getVaultByAddress(address): LeverageYieldVault | undefined;
+```
+
+## Action params shape
+
+```ts
+type LeverageYieldSwapDepositParams = {
+  vault: Address;             // the lsoda* vault proxy
+  srcChainKey: SpokeChainKey; // chain the user holds inputToken on & signs from
+  srcAddress: string;
+  inputToken: string;         // spoke-side token paid in
+  inputAmount: bigint;
+  minOutputAmount: bigint;    // min lsoda* (18 dp), slippage applied
+  deadline?: bigint;          // defaults to hub block timestamp + 5 min
+  solver?: Address;           // 0x0 = any solver
+  partnerFee?: PartnerFee;    // per-intent override; deducted from inputAmount before the swap
+};
+
+type LeverageYieldSwapWithdrawParams = {
+  vault: Address;
+  srcChainKey: SpokeChainKey; // chain the user signs the sendMessage on
+  srcAddress: string;
+  dstChainKey: SpokeChainKey; // where the swapped-back token is delivered
+  outputToken: string;
+  inputAmount: bigint;        // lsoda* shares to burn (18 dp)
+  minOutputAmount: bigint;
+  recipient?: string;         // defaults to srcAddress
+  deadline?: bigint;
+  solver?: Address;
+};
+
+// The execute-mode wrapper (createVaultIntent / vaultSwap). The two vault execution modifiers
+// live HERE, never on the generic swap surface:
+type VaultSwapActionParams<K, Raw> = SpokeExecActionParams<K, Raw, CreateIntentParams<K>> & {
+  hubWalletSwap?: boolean;  // withdraw: inputToken is hub-wallet lsoda*, authorise via Connection.sendMessage
+  partnerFee?: PartnerFee;  // beats config.swaps.partnerFee for this intent only
+};
+```
+
+## Common call shapes
+
+### Deposit (any token → `lsoda*`)
+
+```ts
+const built = await sodax.leverageYield.deposit({
+  vault: vault.vault,
+  srcChainKey: ChainKeys.ARBITRUM_MAINNET,
+  srcAddress: '0x…',
+  inputToken: '0x…weETHonArbitrum',
+  inputAmount: parseUnits('1', 18),
+  minOutputAmount: 0n,                 // quote via sodax.swaps.getQuote (token_dst = vault), then apply slippage
+  partnerFee: { address: '0x…', percentage: 100 }, // optional 1% per-intent fee
+});
+if (!built.ok) return;
+
+const result = await sodax.leverageYield.vaultSwap({ ...built.value, walletProvider });
+if (!result.ok) return;
+const { solverExecutionResponse, intent, intentDeliveryInfo } = result.value;
+```
+
+### Withdraw (`lsoda*` → any token)
+
+```ts
+const built = await sodax.leverageYield.withdraw({
+  vault: vault.vault,
+  srcChainKey: ChainKeys.ARBITRUM_MAINNET, // user signs the sendMessage here
+  srcAddress: '0x…',
+  dstChainKey: ChainKeys.ARBITRUM_MAINNET, // token delivered here
+  outputToken: '0x…weETHonArbitrum',
+  inputAmount: shareBalance,               // lsoda* to burn
+  minOutputAmount: 0n,                     // quote via sodax.swaps.getQuote (token_src = vault)
+});
+if (!built.ok) return;
+// built.value.hubWalletSwap === true — no spoke approval; the hub wallet authorises the spend
+await sodax.leverageYield.vaultSwap({ ...built.value, walletProvider });
+```
+
+### Manual create → relay → notify
+
+```ts
+const created = await sodax.leverageYield.createVaultIntent({ ...built.value, raw: false, walletProvider });
+if (!created.ok) return;
+const { tx, relayData } = created.value;
+// relay `tx` with the shared relayTxAndWaitPacket helper using relayData, then:
+await sodax.leverageYield.notifySolver({ intent_tx_hash: hubIntentTxHash });
+```
+
+## Return shapes
+
+| Method | Success type |
+|---|---|
+| `deposit`, `withdraw` | `LeverageYieldSwapPayload` (`{ params: CreateIntentParams; hubWalletSwap?: true; partnerFee? }`) |
+| `createVaultIntent` | `CreateVaultIntentResult<K, Raw>` (`{ tx, intent & feeAmount, relayData }`) |
+| `vaultSwap` | `VaultSwapResponse` (`{ solverExecutionResponse, intent, intentDeliveryInfo }`) |
+| `notifySolver` | `SolverExecutionResponse` (`{ answer, intent_hash }`) |
+| `approve` | `TxReturnType<HubChainKey, R>` |
+| `isAllowanceValid` | `boolean` |
+| `getApr` | `LeverageYieldApr` (`{ supplyAprRay, borrowAprRay, targetLtvBps, leverageMultiplierWad, netAprRay }`, RAY/WAD) |
+| `getEffectiveApr` | `LeverageYieldEffectiveApr` (= `LeverageYieldApr & { lsdApr, effectiveSupplyAprRay, effectiveNetAprRay }`) |
+| `getLsdApr` | `LeverageYieldLsdApr` (`{ aprRay, label, stale }`) |
+| `getPosition` | `LeverageYieldPosition` (`{ collateral, debt, ltv, healthFactor, idleAsset }`) |
+| `getTotalAssets`, `preview*`, `getMaxWithdraw*`, `getShareBalance*` | `bigint` |
+| `getAsset` | `Address` |
+| `listVaults` / `getVault` / `getVaultByAddress` | `LeverageYieldVault[]` / `LeverageYieldVault \| undefined` (synchronous) |
+
+## Error codes
+
+`feature: 'leverageYield'`. Action discriminator on `context.action`: `'deposit' | 'withdraw' | 'approve' | 'allowanceCheck' | 'vaultSwap'`. Read methods partition on `context.method`.
+
+| Method | Narrow code union |
+|---|---|
+| `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) |
+| `createVaultIntent` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| UNKNOWN` (create-intent subset) |
+| `vaultSwap` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` |
+| `notifySolver` | `EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` (with `phase: 'postExecution'`) |
+| `approve` | `VALIDATION_FAILED \| APPROVE_FAILED \| UNKNOWN` |
+| `isAllowanceValid` | `VALIDATION_FAILED \| ALLOWANCE_CHECK_FAILED \| UNKNOWN` (action `'allowanceCheck'`) |
+| Read methods | `VALIDATION_FAILED \| LOOKUP_FAILED \| UNKNOWN` (with `method` discriminator) |
+
+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.
+
+## Cross-references
+
+- ERC-4626 share-as-token model, APR math, and the deliberate swap-domain duplication: SDK source `packages/sdk/docs/LEVERAGE_YIELD.md`.
+- For React Query hooks over this surface, load the `sodax-dapp-kit` skill (integration mode) — its `features/leverage-yield.md`.
+- v2-only feature — no migration sibling.

package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md

@@ -29,7 +29,8 @@ type SodaxFeature =
   | 'migration'
   | 'dex'
   | 'partner'
-  | 'recovery';
+  | 'recovery'
+  | 'leverageYield';
 ```
 
 The `(feature, code)` pair is the canonical discriminator. Loggers tag both fields; switch statements branch on both.
@@ -156,6 +157,21 @@ type LookupErrorCode = 'VALIDATION_FAILED' | 'LOOKUP_FAILED' | 'UNKNOWN';
 
 Both follow the same shape: action methods get the full exec union (`'EXECUTION_FAILED' \| 'INTENT_CREATION_FAILED' \| ...`), read methods get `LookupErrorCode`, approve methods get `ApproveErrorCode`.
 
+### Leverage Yield (`feature: 'leverageYield'`)
+
+Action discriminator on `context.action`: `'deposit' \| 'withdraw' \| 'approve' \| 'allowanceCheck' \| 'vaultSwap'`.
+
+| Method | Narrow code union |
+|---|---|
+| `deposit`, `withdraw`, `createVaultIntent` | `CreateIntentErrorCode` (create-intent subset) |
+| `vaultSwap` | All exec codes: `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` |
+| `notifySolver` | `EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` (with `phase: 'postExecution'`) |
+| `approve` | `ApproveErrorCode` |
+| `isAllowanceValid` | `AllowanceCheckErrorCode` (action `'allowanceCheck'`) |
+| `getApr`, `getEffectiveApr`, `getLsdApr`, `getPosition`, `getTotalAssets`, `previewDeposit`, `previewWithdraw`, `previewRedeem`, `getMaxWithdraw`, `getMaxWithdrawForUser`, `getShareBalance`, `getShareBalanceForUser`, `getAsset` | `LookupErrorCode` (with `method` discriminator) |
+
+Relay/tx-verification codes appear only on `vaultSwap`; `createVaultIntent` stays within the create-intent subset. `notifySolver` is public (manual create→relay→notify) and emits the post-execution subset.
+
 ---
 
 

package/skills/sodax-sdk/integration/knowledge/reference/public-api.md

@@ -67,6 +67,7 @@ import {
   dexInvariant,
   partnerInvariant,
   recoveryInvariant,
+  leverageYieldInvariant,
   mapRelayFailure,
 
   // Tokens
@@ -108,6 +109,17 @@ import {
   type ClClaimRewardsParams,
   type MigrationParams,
   type UnifiedBnUSDMigrateParams,
+  type LeverageYieldSwapDepositParams,
+  type LeverageYieldSwapWithdrawParams,
+  type LeverageYieldSwapPayload,
+  type VaultSwapActionParams,
+  type VaultSwapResponse,
+  type CreateVaultIntentResult,
+  type LeverageYieldApr,
+  type LeverageYieldEffectiveApr,
+  type LeverageYieldLsdApr,
+  type LeverageYieldPosition,
+  type LeverageYieldVault,
   // …
 
   // Backend / relay

package/skills/sodax-sdk/leverage-yield/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: sodax-sdk-leverage-yield
+description: 'Granular skill for the @sodax/sdk v2 leverage-yield feature only — leveraged-yield ERC-4626 vaults on Sonic via LeverageYieldService. Deposit any token → lsoda* shares, withdraw shares → any token (both as solver-tradeable intent swaps), createVaultIntent/vaultSwap/notifySolver, Sonic-direct approve/isAllowanceValid, and reads (getApr, getEffectiveApr, getPosition, getTotalAssets, preview*, getMaxWithdraw*, getShareBalance*, listVaults). Use when the task is leverage-yield vaults (e.g. "deposit into a leverage vault", "withdraw lsoda shares", "vault APR / effective APR", "leverage vault position / health factor", "lsoda share balance"). New in v2 — integration only, no v1 migration path. Links into the parent sodax-sdk knowledge tree. For React dapps, prefer sodax-dapp-kit.'
+---
+
+# Leverage Yield (Core SDK granular skill)
+
+Granular skill for `LeverageYieldService` — `sodax.leverageYield`. Feature tag: `'leverageYield'`. **New in v2; no v1 migration path.**
+
+## Step 1 — Clarify with user before coding
+
+1. **Deposit or withdraw?** Deposit = any spoke token → `lsoda*` shares (delivered to the user's hub wallet). Withdraw = `lsoda*` shares (in the hub wallet) → any token on any chain.
+2. **Build vs execute.** `deposit` / `withdraw` only *build* a `LeverageYieldSwapPayload`; `vaultSwap` *executes* it end-to-end. Spread the built payload into `vaultSwap({ ...payload, walletProvider })`.
+3. **End-to-end or manual relay?** `vaultSwap` does create → verify → relay → notify. For backend submit-tx, use `createVaultIntent` then relay yourself and finish with the public `notifySolver`.
+4. **Reads?** `getEffectiveApr` (headline, AAVE + LSD), `getApr` (AAVE-only — can be negative), `getPosition`, `getTotalAssets`, `previewRedeem`, `getMaxWithdrawForUser` / `getShareBalanceForUser` (resolve the hub wallet from a spoke address internally).
+
+## Integration workflow
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
+2. [`../integration/knowledge/features/leverage-yield.md`](../integration/knowledge/features/leverage-yield.md) — `LeverageYieldService` API, the share-as-token model, deposit/withdraw/vaultSwap flows, APR math.
+3. Path-specific recipe:
+   - Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
+   - Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
+4. Errors (`feature: 'leverageYield'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
+
+### Leverage-yield-specific anti-patterns
+
+- **Expecting `deposit` / `withdraw` to broadcast.** They are builders returning a `LeverageYieldSwapPayload`. Execute via `vaultSwap({ ...payload, walletProvider })`.
+- **Using `getApr` as the headline number.** For LSD-backed vaults the AAVE-only spread is often negative; `getEffectiveApr` folds in the LSD staking yield (the real source of return).
+- **Passing a spoke address to `getShareBalance` / `getMaxWithdraw`.** Those take a hub address. Use the `*ForUser(vault, srcChainKey, srcAddress)` variants to resolve the hub wallet first.
+- **Gating withdraw on `approve` / `isAllowanceValid`.** Those are Sonic-direct allowance helpers for the vault's underlying asset; the swap-style withdraw authorises the share spend via a hub-wallet `Connection.sendMessage` (`hubWalletSwap: true`).
+- **Quoting on the pre-fee amount.** A deposit's per-intent `partnerFee` is deducted from `inputAmount` before the swap — quote (via the swap solver, `token_dst` = vault) on the post-fee amount.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Every `await sodax.leverageYield.<method>(...)` has `if (!result.ok)`.
+3. Deposit/withdraw build a payload that is then run through `vaultSwap` (or `createVaultIntent` + relay + `notifySolver`).
+4. APR display uses `getEffectiveApr`; share/withdraw sizing from a spoke address uses the `*ForUser` reads.
+
+## Related granular skills (same family)
+
+- [`../swap/SKILL.md`](../swap/SKILL.md) — `vaultSwap` is a leverage-yield copy of the swap intent flow; quote `minOutputAmount` via the solver quote there.
+- [`../recovery/SKILL.md`](../recovery/SKILL.md) — recover stuck hub-wallet assets (including `lsoda*` shares) back to a spoke chain.
+
+For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).