@sodax/skills 2.2.0-rc.2 → 2.2.0-rc.4

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/AGENTS.md CHANGED
@@ -10,7 +10,7 @@ This package ships **mode-gated broad SDK skills** (`skills/<name>/SKILL.md`, on
10
10
 
11
11
  | SDK package | Broad skill | Granular per-feature skills |
12
12
  |---|---|---|
13
- | `@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/sponsoring`, `sodax-sdk/backend-api`, `sodax-sdk/swaps-api` |
13
+ | `@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/sponsoring`, `sodax-sdk/backend-api`, `sodax-sdk/swaps-api`, `sodax-sdk/leverage-yield-api` |
14
14
  | `@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` |
15
15
  | `@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` |
16
16
  | `@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` |
@@ -26,7 +26,7 @@ Pick the consumer's situation, load the listed skills in order. Each entry names
26
26
  | Consumer is… | Load skills (mode) |
27
27
  |---|---|
28
28
  | **Not sure what to build / not a developer** (no SDK, feature, or concrete product chosen yet) | `sodax-build` (front-door ideation: interview → product brief → handoff; it names the dev skills to load next). Skip the moment any SDK / feature / hook is named |
29
- | **Scaffolding ONE specific Core SDK feature** (swap, money-market, bridge, staking, dex, leverage-yield, migration, partner, recovery, sponsoring, backend-api, swaps-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 |
29
+ | **Scaffolding ONE specific Core SDK feature** (swap, money-market, bridge, staking, dex, leverage-yield, migration, partner, recovery, sponsoring, backend-api, swaps-api, leverage-yield-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 |
30
30
  | **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 |
31
31
  | **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 |
32
32
  | **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 |
@@ -64,7 +64,7 @@ packages/skills/
64
64
  ├── sodax-sdk/ {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
65
65
  │ <feature>/SKILL.md children — swap, money-market, bridge, staking, dex,
66
66
  │ leverage-yield, migration, partner, recovery, sponsoring, backend-api,
67
- │ swaps-api}
67
+ │ swaps-api, leverage-yield-api}
68
68
  ├── sodax-wallet-sdk-core/ {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
69
69
  │ <chain>/SKILL.md children — evm, solana, sui, bitcoin, stellar, icon,
70
70
  │ injective, near, stacks}
package/README.md CHANGED
@@ -13,7 +13,7 @@ Using the [`skills` CLI](https://github.com/vercel-labs/skills) from Vercel Labs
13
13
  npx skills@latest add icon-project/sodax-sdks/packages/skills
14
14
  ```
15
15
 
16
- The installable skills listed in `.claude-plugin/plugin.json` land in your repo — the `sodax-build` front-door / ideation skill plus the mode-gated per-SDK-package skills (each with two knowledge subtrees: `integration/` for new v2 code, `migration-v1-to-v2/` for v1→v2 porting) — alongside a router `AGENTS.md`. Re-running the command picks up the latest content.
16
+ The five installable skills listed in `.claude-plugin/plugin.json` land in your repo — the `sodax-build` front-door / ideation skill plus the four mode-gated per-SDK-package skills (each with two knowledge subtrees: `integration/` for new v2 code, `migration-v1-to-v2/` for v1→v2 porting). The CLI does **not** copy the package-level `AGENTS.md`; agents auto-discover each skill from its `SKILL.md` frontmatter. Re-running the command picks up the latest content.
17
17
 
18
18
  > **npm fallback** (web chats or when you prefer a devDependency): `pnpm add -D @sodax/skills`, then point your agent at `node_modules/@sodax/skills/AGENTS.md`. See the [integration guide](https://github.com/icon-project/sodax-sdks/blob/main/docs/ai-integration-guide.md#wire-your-agent).
19
19
 
@@ -25,7 +25,7 @@ The installable skills listed in `.claude-plugin/plugin.json` land in your repo
25
25
  | **Mode-gated per-SDK-package skills** under `skills/sodax-<pkg>/SKILL.md` | One skill per SODAX SDK package. `<pkg>` ∈ `sdk`, `wallet-sdk-core`, `wallet-sdk-react`, `dapp-kit`. Each SKILL.md gates by mode (integration vs migration) at the top of the body. |
26
26
  | **Granular skills** bundled inside each broad skill at `skills/sodax-<pkg>/<sub-domain>/SKILL.md` | Every broad skill ships focused single-domain children: `sodax-sdk` / `sodax-dapp-kit` per feature (swap, money-market, bridge, staking, dex, …); `sodax-wallet-sdk-core` per chain (evm, solana, sui, bitcoin, stellar, icon, injective, near, stacks); `sodax-wallet-sdk-react` per connectivity concern (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect). They install **with** their parent broad skill (not as separate packages); once installed, load one when the task is already scoped to a single sub-domain — it points at exactly the knowledge files for it instead of the whole broad skill. |
27
27
  | **Knowledge** under `skills/sodax-<pkg>/{integration,migration-v1-to-v2}/knowledge/` | Long-form supporting docs — features, recipes, reference tables, breaking-change writeups, code examples. Each skill ships both mode subtrees so `npx skills add` copies the full reference together. |
28
- | **`AGENTS.md`** at the package root | Tool-neutral router: maps the consumer's stated task to the right skill + mode. |
28
+ | **`AGENTS.md`** at the package root | Tool-neutral router: maps the consumer's stated task to the right skill + mode. Ships on npm, so it is the entry point for the `pnpm add -D @sodax/skills` and `file:` installs — the skills CLI does not copy it. |
29
29
 
30
30
  Skills are short and action-oriented (workflow + anti-patterns + links). Knowledge is the lookup material. Don't read knowledge files top-to-bottom — the skill tells the agent which file is relevant for the current task.
31
31
 
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "2.2.0-rc.2",
7
+ "version": "2.2.0-rc.4",
8
8
  "license": "MIT",
9
9
  "description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
10
10
  "keywords": [
@@ -218,26 +218,30 @@ Nothing about the hook contract changes and there is no flag to set. What matter
218
218
  - If the second signature is rejected after the reset landed, the allowance is now zero, so the next
219
219
  attempt is a single transaction — retrying is always safe.
220
220
 
221
- On the unsigned (backend-API) paths, prefer **`useSwapsApiApproveAndBroadcast`** — or
222
- **`useBridgeApiApproveAndBroadcast`** for a bridge: each asks its API for the transactions, then
223
- signs, broadcasts, and waits for each, resolving with `{ approveTxHash, resetTxHash? }` only once the
224
- final approval has landed. A transaction that mines but reverts rejects the mutation naming that
225
- step, so the approve is never sent over a reset that did not take. Each also invalidates its own
226
- allowance query (`['swapsApi','allowance']` / `['bridgeApi','allowance']`), because confirmation now
227
- happens inside the hook. Pick the one matching the action you are about to take — swaps and bridge
228
- approve different spenders on the hub, so an approval built by one does not satisfy the other.
229
-
230
- Both accept an optional **`onProgress`** in their mutation vars. It reports each transaction as
221
+ On the unsigned (backend-API) paths, prefer **`useSwapsApiApproveAndBroadcast`** —
222
+ **`useBridgeApiApproveAndBroadcast`** for a bridge, **`useLeverageYieldApiApproveAndBroadcast`** for a
223
+ leverage-yield deposit: each asks its API for the transactions, then signs, broadcasts, and waits for
224
+ each, resolving with `{ approveTxHash, resetTxHash? }` only once the final approval has landed. A
225
+ transaction that mines but reverts rejects the mutation naming that step, so the approve is never
226
+ sent over a reset that did not take. Each also invalidates its own allowance query
227
+ (`['swapsApi','allowance']` / `['bridgeApi','allowance']` / `['leverageYieldApi','allowance']`),
228
+ because confirmation now happens inside the hook. Pick the one matching the action you are about to
229
+ take — each API builds its approval for its own hub spender, so an approval built by one does not
230
+ satisfy the other. Only a leverage-yield **deposit** needs one; a withdraw spends `lsoda*` from the
231
+ hub wallet and never approves.
232
+
233
+ All three accept an optional **`onProgress`** in their mutation vars. It reports each transaction as
231
234
  `{ step, phase, index, total, hash?, error? }` — `step` is `'allowance-reset'` or `'approve'`, `phase`
232
235
  walks `signing → broadcast → confirmed` (or `failed`), and `index`/`total` give "1 of 2" without the
233
236
  caller tracking anything. Advisory: the listener is never awaited, one that throws is ignored rather
234
237
  than aborting a broadcast, and the mutation's own result stays the source of truth. It lives in the
235
238
  vars rather than the hook options so it is never a stale closure.
236
239
 
237
- `useSwapsApiApprove` / `useBridgeApiApprove` still exist and return the API's `{ tx, resetTx? }`
238
- verbatim — use them only when you need to own signing. If you do, broadcast `resetTx` **first and
239
- wait for it to succeed**; the approve is not a valid state transition until the reset has landed, so
240
- sending both together spends the user's gas on a certain revert. Waiting is not enough on its own —
240
+ `useSwapsApiApprove` / `useBridgeApiApprove` / `useLeverageYieldApiApprove` still exist and return
241
+ the API's `{ tx, resetTx? }` verbatim — use them only when you need to own signing. If you do,
242
+ broadcast `resetTx` **first and wait for it to succeed**; the approve is not a valid state
243
+ transition until the reset has landed, so sending both together spends the user's gas on a certain
244
+ revert. Waiting is not enough on its own —
241
245
  check the receipt's status, because a mined-and-reverted reset leaves the allowance exactly where it
242
246
  was.
243
247
 
@@ -176,6 +176,36 @@ await submitBridgeTx({ request, apiConfig: { baseURL: 'https://...' } });
176
176
 
177
177
  > Full list in [hooks-index.md](../reference/hooks-index.md); key shapes in [querykey-conventions.md](../reference/querykey-conventions.md). For non-React callers, `sodax.api.bridge` is documented in the `sodax-sdk` skill (integration mode).
178
178
 
179
+ ### Leverage Yield API (`sodax.api.leverageYield`)
180
+
181
+ Typed React Query wrappers over the backend **Leverage Yield API v2** — `useLeverageYieldApi*` hooks over `sodax.api.leverageYield.*` (vault registry, vault reads, split deposit/withdraw quote + create-intent, deadline, allowance/approve, the intent lifecycle, gas/fees, submit-tx + status). They are the HTTP-API parallel of the on-chain `leverageYield/` hooks (`useLeverageYieldDeposit`/`useLeverageYieldWithdraw`/…, which drive `sodax.leverageYield`). A vault deposit/withdraw IS an intent-based swap, so the intent / gas / fee / submit-tx hooks mirror the swaps family; reads take `{ params, queryOptions }` and the actions are mutations taking `{ mutationOptions }`.
182
+
183
+ ```ts
184
+ // @ai-snippets-skip
185
+ useLeverageYieldApiVaults({ params, queryOptions }); // query → sodax.api.leverageYield.getVaults
186
+ useLeverageYieldApiEffectiveApr({ params, queryOptions }); // query → sodax.api.leverageYield.getEffectiveApr
187
+ useLeverageYieldApiCreateDepositIntent({ mutationOptions }); // mutation → sodax.api.leverageYield.createDepositIntent
188
+ useLeverageYieldApiSubmitTxStatus({ params, queryOptions }); // query → sodax.api.leverageYield.getSubmitTxStatus
189
+ ```
190
+
191
+ Four deltas worth knowing:
192
+
193
+ - **Create-intent is split.** `useLeverageYieldApiCreateDepositIntent` (any token → `lsoda*`) vs `useLeverageYieldApiCreateWithdrawIntent` (`lsoda*` → any token), each with its own quote hook. Only the deposit path has an allowance step — a withdraw spends `lsoda*` from the hub wallet — so `useLeverageYieldApiAllowance` / `useLeverageYieldApiApprove` take the **deposit** body.
194
+ - **`useLeverageYieldApiSubmitTx`'s `request` carries `operation`.** `LeverageYieldSubmitTxRequestV2` is the swaps `SubmitTxRequestV2` plus a required `operation: 'deposit' | 'withdraw'`; `relayData` is the payload **string**, as for swaps.
195
+ - **Terminal submit-tx status is `solved`**, not the bridge API's `executed` — a vault swap is filled by the solver, so `posting_execution` applies too. `useLeverageYieldApiSubmitTxStatus` polls (1s) while both `txHash` and `srcChainKey` are supplied and stops on `solved` / `failed`, on a set `abandonedAt`, or once the backend rejects the API key.
196
+ - **`lsoda*` shares live in the derived HUB wallet, not the EOA.** Resolve it with `useGetUserHubWalletAddress` before reading `useLeverageYieldApiShareBalance` / `useLeverageYieldApiMaxWithdraw`, or the balance reads as zero.
197
+
198
+ ```ts
199
+ // @ai-snippets-skip
200
+ const { mutateAsync: submitVaultTx } = useLeverageYieldApiSubmitTx();
201
+ // request: LeverageYieldSubmitTxRequestV2 — { txHash, srcChainKey, walletAddress, intent, relayData, operation }
202
+ await submitVaultTx({ request, apiConfig: { baseURL: 'https://...' } });
203
+ ```
204
+
205
+ Prefer `useLeverageYieldApiApproveAndBroadcast` over `useLeverageYieldApiApprove`: a guarded deposit token can need its stale allowance cleared first, and the approve-and-broadcast hook owns plan → sign → broadcast → wait in that order (reporting each step through `onProgress`) and invalidates `['leverageYieldApi','allowance']` itself.
206
+
207
+ > Full list in [hooks-index.md](../reference/hooks-index.md); key shapes in [querykey-conventions.md](../reference/querykey-conventions.md). For non-React callers, `sodax.api.leverageYield` is documented in the `sodax-sdk` skill (integration mode).
208
+
179
209
  ## Shared utilities
180
210
 
181
211
  Cross-cutting hooks used by other features.
@@ -2,6 +2,8 @@
2
2
 
3
3
  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).
4
4
 
5
+ > **Backend-API variant:** the hooks below drive the on-chain `LeverageYieldService` (wallet → hub). To call the backend **Leverage Yield API v2** HTTP client (`sodax.api.leverageYield`) directly instead, use the `useLeverageYieldApi*` hooks — typed React Query wrappers over each endpoint (`useLeverageYieldApiVaults`, `useLeverageYieldApiEffectiveApr`, `useLeverageYieldApiDepositQuote` / `useLeverageYieldApiWithdrawQuote`, `useLeverageYieldApiAllowance` / `useLeverageYieldApiApprove`, `useLeverageYieldApiCreateDepositIntent` / `useLeverageYieldApiCreateWithdrawIntent`, `useLeverageYieldApiSubmitTx` / `useLeverageYieldApiSubmitTxStatus`, and the intent-lifecycle/vault-read hooks). Their `queryKey`/`mutationKey` namespace is `leverageYieldApi`. For the endpoint contract, load the `sodax-sdk` skill's leverage-yield-api feature doc.
6
+
5
7
  ## Hook surface
6
8
 
7
9
  ```ts
@@ -231,6 +231,47 @@ Typed React Query wrappers over the backend Bridge API v2 (`sodax.api.bridge.*`)
231
231
  | `useBridgeApiCreateBridgeIntent` | Mutation; builds `{ tx, relayData }` (no intent) |
232
232
  | `useBridgeApiSubmitTx` | Mutation; `request: BridgeSubmitTxRequestV2` (FULL relayData envelope) |
233
233
 
234
+ ## Leverage Yield API (`sodax.api.leverageYield`)
235
+
236
+ Typed React Query wrappers over the backend Leverage Yield API v2 (`sodax.api.leverageYield.*`), one per endpoint. Distinct from the on-chain `leverageYield/` hooks (`useLeverageYieldDeposit`/`useLeverageYieldWithdraw`/…), which drive `sodax.leverageYield` (the `LeverageYieldService`). A vault deposit/withdraw IS an intent-based swap, so the intent / gas / fee / submit-tx hooks mirror the swaps family; the vault registry, vault reads and the split deposit/withdraw quote + create-intent hooks are leverage-yield's own.
237
+
238
+ | Hook | Type / Polling |
239
+ |---|---|
240
+ | `useLeverageYieldApiVaults` | Query; the deployed-vault registry |
241
+ | `useLeverageYieldApiVault` | Query; one vault descriptor by lsoda* `name` |
242
+ | `useLeverageYieldApiAsset` | Query; the vault's underlying hub asset |
243
+ | `useLeverageYieldApiPosition` | Query; `{ collateral, debt, ltv, healthFactor, idleAsset }` |
244
+ | `useLeverageYieldApiApr` | Query; AAVE-only steady-state APR (RAY strings; can be negative) |
245
+ | `useLeverageYieldApiEffectiveApr` | Query; combined AAVE + LSD APR — `effectiveNetAprRay` is the headline |
246
+ | `useLeverageYieldApiLsdApr` | Query; off-chain LSD staking-APR snapshot |
247
+ | `useLeverageYieldApiTotalAssets` | Query; total assets under management |
248
+ | `useLeverageYieldApiPreviewDeposit` | Query; ERC-4626 `previewDeposit` — shares for `assets` |
249
+ | `useLeverageYieldApiPreviewWithdraw` | Query; ERC-4626 `previewWithdraw` — shares burned for `assets` |
250
+ | `useLeverageYieldApiPreviewRedeem` | Query; ERC-4626 `previewRedeem` — assets for `shares` |
251
+ | `useLeverageYieldApiShareBalance` | Query; an owner's lsoda* balance (the HUB wallet, not the EOA) |
252
+ | `useLeverageYieldApiMaxWithdraw` | Query; RAW ERC-4626 `maxWithdraw` — NOT dust-trimmed, apply a margin for a MAX withdraw |
253
+ | `useLeverageYieldApiDepositQuote` | Query; any token → lsoda* (set `query.includeTxData` for `txData`) |
254
+ | `useLeverageYieldApiWithdrawQuote` | Query; lsoda* → any token |
255
+ | `useLeverageYieldApiDeadline` | Query; computed vault-swap deadline |
256
+ | `useLeverageYieldApiAllowance` | Query; `{ valid }` — the DEPOSIT body only (withdraw needs no spoke allowance) |
257
+ | `useLeverageYieldApiStatus` | Query (1s); polls until status `3` (SOLVED) / `4` (FAILED) |
258
+ | `useLeverageYieldApiIntentHash` | Query; keccak256 of an intent struct |
259
+ | `useLeverageYieldApiIntentPacket` | Query; long-polls the relayer for the fill packet (no client interval) |
260
+ | `useLeverageYieldApiIntentExtraData` | Query; relay extra-data for submit |
261
+ | `useLeverageYieldApiFilledIntent` | Query; on-chain fill state by tx hash |
262
+ | `useLeverageYieldApiIntent` | Query; decoded intent struct by tx hash |
263
+ | `useLeverageYieldApiEstimateGas` | Query; gas estimate for a raw tx |
264
+ | `useLeverageYieldApiPartnerFee` | Query; partner fee for an amount |
265
+ | `useLeverageYieldApiSolverFee` | Query; protocol (solver) fee for an amount |
266
+ | `useLeverageYieldApiSubmitTxStatus` | Query (1s); requires `txHash` + `srcChainKey`; polls until `solved` / `failed` / `abandonedAt` |
267
+ | `useLeverageYieldApiApprove` | Mutation; builds unsigned approval tx(s) — `{ tx, resetTx? }`, ordering is yours to handle |
268
+ | `useLeverageYieldApiApproveAndBroadcast` | Mutation; builds **and** signs/broadcasts/waits — preferred; `{ approveTxHash, resetTxHash? }`; optional `onProgress` per step |
269
+ | `useLeverageYieldApiCreateDepositIntent` | Mutation; builds `{ tx, intent, relayData }` (any token → lsoda*) |
270
+ | `useLeverageYieldApiCreateWithdrawIntent` | Mutation; builds `{ tx, intent, relayData }` (lsoda* → any token) |
271
+ | `useLeverageYieldApiSubmitIntent` | Mutation; submits broadcast intent to the relay |
272
+ | `useLeverageYieldApiCancelIntent` | Mutation; builds unsigned cancel tx |
273
+ | `useLeverageYieldApiSubmitTx` | Mutation; `request: LeverageYieldSubmitTxRequestV2` — the swaps body PLUS a required `operation: 'deposit' \| 'withdraw'` |
274
+
234
275
  ## Partner
235
276
 
236
277
  | Hook | Type | Purpose |
@@ -202,6 +202,47 @@ Typed wrappers over `sodax.api.bridge.*` (one per Bridge API v2 endpoint), all k
202
202
  | `['bridgeApi', 'createBridgeIntent']` | `useBridgeApiCreateBridgeIntent` mutation |
203
203
  | `['bridgeApi', 'submitTx']` | `useBridgeApiSubmitTx` mutation |
204
204
 
205
+ ### Leverage Yield API (`sodax.api.leverageYield`)
206
+
207
+ Typed wrappers over `sodax.api.leverageYield.*` (one per Leverage Yield API v2 endpoint), all keyed `['leverageYieldApi', action, ...]`.
208
+
209
+ | Key | Hook |
210
+ |---|---|
211
+ | `['leverageYieldApi', 'vaults']` | `useLeverageYieldApiVaults` |
212
+ | `['leverageYieldApi', 'vault', name]` | `useLeverageYieldApiVault` |
213
+ | `['leverageYieldApi', 'asset', vault]` | `useLeverageYieldApiAsset` |
214
+ | `['leverageYieldApi', 'position', vault]` | `useLeverageYieldApiPosition` |
215
+ | `['leverageYieldApi', 'apr', vault]` | `useLeverageYieldApiApr` |
216
+ | `['leverageYieldApi', 'effectiveApr', vault]` | `useLeverageYieldApiEffectiveApr` |
217
+ | `['leverageYieldApi', 'lsdApr', vault]` | `useLeverageYieldApiLsdApr` |
218
+ | `['leverageYieldApi', 'totalAssets', vault]` | `useLeverageYieldApiTotalAssets` |
219
+ | `['leverageYieldApi', 'previewDeposit', vault, assets]` | `useLeverageYieldApiPreviewDeposit` |
220
+ | `['leverageYieldApi', 'previewWithdraw', vault, assets]` | `useLeverageYieldApiPreviewWithdraw` |
221
+ | `['leverageYieldApi', 'previewRedeem', vault, shares]` | `useLeverageYieldApiPreviewRedeem` |
222
+ | `['leverageYieldApi', 'shareBalance', vault, owner]` | `useLeverageYieldApiShareBalance` |
223
+ | `['leverageYieldApi', 'maxWithdraw', vault, owner]` | `useLeverageYieldApiMaxWithdraw` |
224
+ | `['leverageYieldApi', 'depositQuote', …]` | `useLeverageYieldApiDepositQuote` |
225
+ | `['leverageYieldApi', 'withdrawQuote', …]` | `useLeverageYieldApiWithdrawQuote` |
226
+ | `['leverageYieldApi', 'deadline', …]` | `useLeverageYieldApiDeadline` |
227
+ | `['leverageYieldApi', 'allowance', …]` | `useLeverageYieldApiAllowance` |
228
+ | `['leverageYieldApi', 'status', intentTxHash]` | `useLeverageYieldApiStatus` |
229
+ | `['leverageYieldApi', 'intentHash', …]` | `useLeverageYieldApiIntentHash` |
230
+ | `['leverageYieldApi', 'intentPacket', …]` | `useLeverageYieldApiIntentPacket` |
231
+ | `['leverageYieldApi', 'intentExtraData', …]` | `useLeverageYieldApiIntentExtraData` |
232
+ | `['leverageYieldApi', 'filledIntent', txHash]` | `useLeverageYieldApiFilledIntent` |
233
+ | `['leverageYieldApi', 'intent', txHash]` | `useLeverageYieldApiIntent` |
234
+ | `['leverageYieldApi', 'estimateGas', …]` | `useLeverageYieldApiEstimateGas` |
235
+ | `['leverageYieldApi', 'partnerFee', amount]` | `useLeverageYieldApiPartnerFee` |
236
+ | `['leverageYieldApi', 'solverFee', amount]` | `useLeverageYieldApiSolverFee` |
237
+ | `['leverageYieldApi', 'submitTx', 'status', txHash, srcChainKey]` | `useLeverageYieldApiSubmitTxStatus` — both identifiers required |
238
+ | `['leverageYieldApi', 'approve']` | `useLeverageYieldApiApprove` mutation |
239
+ | `['leverageYieldApi', 'approveAndBroadcast']` | `useLeverageYieldApiApproveAndBroadcast` mutation |
240
+ | `['leverageYieldApi', 'createDepositIntent']` | `useLeverageYieldApiCreateDepositIntent` mutation |
241
+ | `['leverageYieldApi', 'createWithdrawIntent']` | `useLeverageYieldApiCreateWithdrawIntent` mutation |
242
+ | `['leverageYieldApi', 'submitIntent']` | `useLeverageYieldApiSubmitIntent` mutation |
243
+ | `['leverageYieldApi', 'cancelIntent']` | `useLeverageYieldApiCancelIntent` mutation |
244
+ | `['leverageYieldApi', 'submitTx']` | `useLeverageYieldApiSubmitTx` mutation |
245
+
205
246
  ### Leverage Yield
206
247
 
207
248
  | Key | Hook |
@@ -36,6 +36,7 @@ If the user has already picked a single feature, load the matching granular skil
36
36
  | Sponsored Stellar account activation | [`./sponsoring/SKILL.md`](./sponsoring/SKILL.md) | "activate a Stellar account", "user has no XLM", "sponsor base reserve", "sodax.sponsoring" |
37
37
  | Backend HTTP client (intents, orderbook, MM reads) | [`./backend-api/SKILL.md`](./backend-api/SKILL.md) | "getIntentByHash", "Sodax backend API", "orderbook", "custom IConfigApiV1" |
38
38
  | Swaps API v2 client (quote, create-intent, submit-tx, fees) | [`./swaps-api/SKILL.md`](./swaps-api/SKILL.md) | "sodax.api.swaps", "swap quote from backend", "submit swap tx", "swaps API v2" |
39
+ | Leverage Yield API v2 client (vault reads, APR, deposit/withdraw quote + intents) | [`./leverage-yield-api/SKILL.md`](./leverage-yield-api/SKILL.md) | "sodax.api.leverageYield", "vault APR from backend", "vault position from API", "leverage-yield API v2" |
39
40
  | Bridge API v2 client (allowance/approve, create-intent, submit-tx, tokens, fee/bridgeable discovery) | [`./bridge-api/SKILL.md`](./bridge-api/SKILL.md) | "sodax.api.bridge", "createBridgeIntent via backend", "submit bridge tx", "bridge API v2" |
40
41
 
41
42
  Load this broad skill (keep reading below) when:
@@ -78,7 +79,7 @@ Follow in order. Skipping `ai-rules.md` is the most common cause of agents rever
78
79
 
79
80
  1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DO NOT / workflow / stop conditions.
80
81
  2. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — install, initialize, first-run troubleshooting.
81
- 3. For your feature, read [`integration/knowledge/features/`](./integration/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `partner.md`, `recovery.md`, `sponsoring.md`, `backend-api.md`, `swaps-api.md`, `bridge-api.md`.
82
+ 3. For your feature, read [`integration/knowledge/features/`](./integration/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `leverage-yield.md`, `migration.md`, `partner.md`, `recovery.md`, `sponsoring.md`, `backend-api.md`, `swaps-api.md`, `bridge-api.md`, `leverage-yield-api.md`.
82
83
  4. For specific patterns (init, raw vs signed, chain narrowing, gas, testing, errors, logging), read [`integration/knowledge/recipes/`](./integration/knowledge/recipes/).
83
84
  5. Lookups (chain keys, error codes, public API surface, wallet provider types, glossary) → [`integration/knowledge/reference/`](./integration/knowledge/reference/).
84
85
  6. Non-EVM quirks (Stellar trustline, BTC PSBT, Solana PDA, ICON, NEAR) → [`integration/knowledge/chain-specifics.md`](./integration/knowledge/chain-specifics.md).
@@ -240,7 +240,7 @@ Deposits **from** NEAR (`deposit()` / `fillIntent()` on the NEAR spoke service)
240
240
  | Chain | Notes |
241
241
  |---|---|
242
242
  | **Sui** (`SUI_MAINNET`) | Address: 32-byte `0x…` (different from EVM addresses despite the prefix). Wallet provider `ISuiWalletProvider` uses `@mysten/sui` under the hood. Reads and submission go over gRPC-web (`grpc_url`, default `https://fullnode.mainnet.sui.io`; `rpc_url` remains a deprecated alias that wins when set) — Mysten's public fullnodes stopped serving JSON-RPC in July 2026, and `sui-node` drops it in October 2026. |
243
- | **Stacks** (`STACKS_MAINNET`) | Address: `SP…` (mainnet) / `ST…` (testnet). Uses `@stacks/transactions` for tx construction. |
243
+ | **Stacks** (`STACKS_MAINNET`) | Address: `SP…` (mainnet) / `ST…` (testnet). Uses `@stacks/transactions` for tx construction. Wallet-signed deposits use post-condition mode `Deny` with exact spend caps (uSTX for native; one cap per fungible token the SIP-10 contract defines), so wallets display the exact spend and anything beyond it aborts on-chain. FT deposits resolve the on-chain asset names via the node's contract-interface endpoint and fail before signing if that lookup fails; `raw: true` skips the lookup — the serialized payload cannot carry post-conditions. |
244
244
  | **Injective** (`INJECTIVE_MAINNET`) | Cosmos-ecosystem chain. Address: `inj1…`. Wallet provider uses `@injectivelabs/sdk-ts`. |
245
245
 
246
246
  Each has its own `I*WalletProvider` interface with chain-specific signing methods. The `chainType` discriminant on every `I*WalletProvider` instance lets you narrow at runtime without `instanceof`.
@@ -17,9 +17,10 @@ One file per feature service. Each file documents the v2 API surface, common cal
17
17
  | [`sponsoring.md`](sponsoring.md) | `SponsoringService` | Stellar account activation via sponsored reserves. The sponsor pays the base reserve; the user's wallet signs. |
18
18
  | [`swaps-api.md`](swaps-api.md) | `SwapsApiService` | Typed HTTP client for the backend Swaps API v2 (`sodax.api.swaps`, `/swaps/*`). Quote, create-intent, submit-tx + status, fees. |
19
19
  | [`bridge-api.md`](bridge-api.md) | `BridgeApiService` | Typed HTTP client for the backend Bridge API v2 (`sodax.api.bridge`, `/bridge/*`). Allowance/approve/create-intent, submit-tx + status, tokens. |
20
+ | [`leverage-yield-api.md`](leverage-yield-api.md) | `LeverageYieldApiService` | Typed HTTP client for the backend Leverage Yield API v2 (`sodax.api.leverageYield`, `/leverage-yield/*`). Vault registry + reads, deposit/withdraw quote + intents, submit-tx + status, fees. |
20
21
 
21
22
  All feature services are constructed and wired by the `Sodax` facade. You don't instantiate them directly — access them via `sodax.swaps`, `sodax.moneyMarket`, etc. See [`../architecture.md`](../architecture.md) for the service graph.
22
23
 
23
24
  ## Cross-references to migration
24
25
 
25
- 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.
26
+ 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`, `leverage-yield-api.md`, `swaps-api.md`) have no migration sibling — there is nothing to port.
@@ -0,0 +1,234 @@
1
+ # Leverage Yield API — `LeverageYieldApiService`
2
+
3
+ Typed HTTP client for the backend **Leverage Yield API v2** (`/leverage-yield/*`). Reachable as
4
+ `sodax.api.leverageYield` (`sodax.api` is an alias for `sodax.backendApi`; `.leverageYield` is the
5
+ `LeverageYieldApiService` instance). One method per endpoint (33 total). Every method returns
6
+ `Promise<Result<T>>` — it **never throws** — and every response is validated at runtime against a valibot
7
+ schema, so a backend contract drift surfaces as `{ ok: false }` rather than an untyped object.
8
+
9
+ Access: `sodax.api.leverageYield`. Service class: `LeverageYieldApiService`. **Errors:** every failure
10
+ (network, timeout, non-2xx HTTP, or response-shape mismatch) returns
11
+ `Result<T, SodaxError<'EXTERNAL_API_ERROR'>>` with `feature: 'backend'`, `context.api: 'leverageYield'`,
12
+ and `context.endpoint` (the path). The underlying failure is preserved on `error.cause`. This differs from
13
+ the feature service (`sodax.leverageYield`), whose errors carry `feature: 'leverageYield'` — the
14
+ leverage-yield **HTTP client** is uniformly `feature: 'backend'`, exactly like `sodax.api.swaps`.
15
+
16
+ A leverage-yield deposit/withdraw **is** an intent-based swap (the vault's `lsoda*` share token is a
17
+ solver-tradeable token), so the intent-relay / gas / fee / submit-tx endpoints share the same wire shapes
18
+ as the Swaps API — this client is the leverage-yield sibling of [`swaps-api.md`](swaps-api.md).
19
+
20
+ ## Methods
21
+
22
+ ```ts
23
+ // Vault registry
24
+ sodax.api.leverageYield.getVaults(config?): Promise<Result<GetLeverageVaultsResponseV2>>;
25
+ sodax.api.leverageYield.getVault(name, config?): Promise<Result<GetLeverageVaultResponseV2>>;
26
+
27
+ // Vault reads — all take a { vault } query (some also { owner } / { assets } / { shares })
28
+ sodax.api.leverageYield.getAsset(query: VaultQueryV2, config?): Promise<Result<VaultAssetResponseV2>>;
29
+ sodax.api.leverageYield.getPosition(query: VaultQueryV2, config?): Promise<Result<LeverageYieldPositionV2>>;
30
+ sodax.api.leverageYield.getApr(query: VaultQueryV2, config?): Promise<Result<LeverageYieldAprV2>>;
31
+ sodax.api.leverageYield.getEffectiveApr(query: VaultQueryV2, config?): Promise<Result<LeverageYieldEffectiveAprV2>>;
32
+ sodax.api.leverageYield.getLsdApr(query: VaultQueryV2, config?): Promise<Result<LeverageYieldLsdAprV2>>;
33
+ sodax.api.leverageYield.getTotalAssets(query: VaultQueryV2, config?): Promise<Result<VaultTotalAssetsResponseV2>>;
34
+ sodax.api.leverageYield.previewDeposit(query: VaultAssetsQueryV2, config?): Promise<Result<PreviewDepositResponseV2>>;
35
+ sodax.api.leverageYield.previewWithdraw(query: VaultAssetsQueryV2, config?): Promise<Result<PreviewWithdrawResponseV2>>;
36
+ sodax.api.leverageYield.previewRedeem(query: VaultSharesQueryV2, config?): Promise<Result<PreviewRedeemResponseV2>>;
37
+ sodax.api.leverageYield.getShareBalance(query: VaultOwnerQueryV2, config?): Promise<Result<ShareBalanceResponseV2>>;
38
+ sodax.api.leverageYield.getMaxWithdraw(query: VaultOwnerQueryV2, config?): Promise<Result<MaxWithdrawResponseV2>>;
39
+
40
+ // Quote (separate deposit / withdraw) · deadline
41
+ sodax.api.leverageYield.getDepositQuote(body: LeverageYieldDepositQuoteRequestV2, query?: QuoteQueryV2, config?): Promise<Result<QuoteResponseV2>>;
42
+ sodax.api.leverageYield.getWithdrawQuote(body: LeverageYieldWithdrawQuoteRequestV2, query?: QuoteQueryV2, config?): Promise<Result<QuoteResponseV2>>;
43
+ sodax.api.leverageYield.getDeadline(query?: DeadlineQueryV2, config?): Promise<Result<DeadlineResponseV2>>;
44
+
45
+ // Deposit allowance · approve — both share the CreateDepositIntentParamsV2 body (withdraw needs no spoke allowance)
46
+ sodax.api.leverageYield.checkAllowance(body: CreateDepositIntentParamsV2, config?): Promise<Result<AllowanceCheckResponseV2>>;
47
+ sodax.api.leverageYield.approve(body: CreateDepositIntentParamsV2, config?): Promise<Result<ApproveResponseV2>>;
48
+
49
+ // Create intent (separate deposit / withdraw)
50
+ sodax.api.leverageYield.createDepositIntent(body: CreateDepositIntentParamsV2, config?): Promise<Result<CreateIntentResponseV2>>;
51
+ sodax.api.leverageYield.createWithdrawIntent(body: CreateWithdrawIntentParamsV2, config?): Promise<Result<CreateIntentResponseV2>>;
52
+
53
+ // Intent lifecycle: submit · status · cancel · hash · packet · extra-data · fill · get
54
+ sodax.api.leverageYield.submitIntent(body: SubmitIntentRequestV2, config?): Promise<Result<SubmitIntentResponseV2>>;
55
+ sodax.api.leverageYield.getStatus(body: StatusRequestV2, config?): Promise<Result<StatusResponseV2>>;
56
+ sodax.api.leverageYield.cancelIntent(body: CancelIntentRequestV2, config?): Promise<Result<CancelIntentResponseV2>>;
57
+ sodax.api.leverageYield.getIntentHash(body: IntentHashRequestV2, config?): Promise<Result<IntentHashResponseV2>>;
58
+ sodax.api.leverageYield.getSolvedIntentPacket(body: IntentPacketRequestV2, config?): Promise<Result<IntentPacketResponseV2>>;
59
+ sodax.api.leverageYield.getIntentSubmitTxExtraData(body: IntentExtraDataRequestV2, config?): Promise<Result<IntentExtraDataResponseV2>>;
60
+ sodax.api.leverageYield.getFilledIntent(txHash, config?): Promise<Result<IntentStateV2>>;
61
+ sodax.api.leverageYield.getIntent(txHash, config?): Promise<Result<GetIntentResponseV2>>;
62
+
63
+ // Gas · fees
64
+ sodax.api.leverageYield.estimateGas(body: GasEstimateRequestV2, config?): Promise<Result<GasEstimateResponseV2>>;
65
+ sodax.api.leverageYield.getPartnerFee(query: FeeQueryV2, config?): Promise<Result<FeeResponseV2>>;
66
+ sodax.api.leverageYield.getSolverFee(query: FeeQueryV2, config?): Promise<Result<FeeResponseV2>>;
67
+
68
+ // Submit-tx state machine
69
+ sodax.api.leverageYield.submitTx(body: LeverageYieldSubmitTxRequestV2, config?): Promise<Result<SubmitTxResponseV2>>;
70
+ sodax.api.leverageYield.getSubmitTxStatus(query: SubmitTxStatusQueryV2, config?): Promise<Result<SubmitTxStatusResponseV2>>;
71
+ ```
72
+
73
+ The optional trailing `config?: RequestOverrideConfig` (`{ baseURL?, timeout?, headers?, apiKey? }`) on
74
+ every method applies per-call overrides that take precedence over the service config (see "Per-call
75
+ overrides" below).
76
+
77
+ ## Wire shapes — `bigint` vs decimal strings
78
+
79
+ The intent-bearing request bodies (`cancelIntent`, `getIntentHash`, `getIntentSubmitTxExtraData`,
80
+ `submitTx`) take `IntentRequestV2`, whose numeric fields (`intentId`, `inputAmount`, `minOutputAmount`,
81
+ `deadline`, `srcChain`, `dstChain`) are **`bigint`**; the client serializes them to decimal strings on the
82
+ wire. Server-returned intents (`IntentResponseV2`) and every vault read (`getPosition`, `getApr`,
83
+ `getTotalAssets`, previews, `getShareBalance`, …) come back with numeric fields as decimal **`string`**
84
+ (outbound JSON can't carry bigint). APR rates are RAY (`1e27` = 100%) as decimal strings; the vault-share
85
+ (`lsoda*`) is always 18 decimals. The `amount` / `inputAmount` fields on the quote / create-intent request
86
+ bodies are already decimal **strings**.
87
+
88
+ ## Common call shapes
89
+
90
+ ### Vault reads
91
+
92
+ ```ts
93
+ const vaults = await sodax.api.leverageYield.getVaults();
94
+ if (!vaults.ok) return;
95
+ const vault = vaults.value[0].vault; // hub proxy address (doubles as the lsoda* token)
96
+
97
+ const apr = await sodax.api.leverageYield.getEffectiveApr({ vault });
98
+ if (apr.ok) apr.value.effectiveNetAprRay; // RAY decimal string — the headline number
99
+ ```
100
+
101
+ ### Deposit quote
102
+
103
+ ```ts
104
+ const quote = await sodax.api.leverageYield.getDepositQuote({
105
+ vault,
106
+ tokenSrc, tokenSrcChainKey,
107
+ amount: '1000000', // smallest unit of the input token, decimal string
108
+ quoteType: 'exact_input',
109
+ });
110
+ if (!quote.ok) return;
111
+ quote.value.quotedAmount; // expected lsoda* shares, decimal string
112
+ // Pass query `{ includeTxData: true }` (and srcAddress on the body) to also get `txData`.
113
+ ```
114
+
115
+ ### Create deposit intent
116
+
117
+ ```ts
118
+ const created = await sodax.api.leverageYield.createDepositIntent({
119
+ vault, srcChainKey, srcAddress,
120
+ inputToken,
121
+ inputAmount: '1000000',
122
+ minOutputAmount: '990000', // quotedAmount minus slippage
123
+ deadline: '0', // "0" → no expiry; omit to let the backend default from hub block time
124
+ });
125
+ if (!created.ok) return;
126
+ const { tx, intent, relayData } = created.value;
127
+ // Withdraw is the mirror: createWithdrawIntent({ vault, srcChainKey, srcAddress, dstChainKey,
128
+ // outputToken, inputAmount /* lsoda* shares */, minOutputAmount, recipient? }) — the backend sets
129
+ // hubWalletSwap internally (spends lsoda* from the hub wallet), so withdraw needs no spoke allowance.
130
+ ```
131
+
132
+ ### Approve can return TWO transactions
133
+
134
+ ```ts
135
+ // Only a deposit needs a spoke allowance — a withdraw spends lsoda* from the hub wallet.
136
+ const allowance = await sodax.api.leverageYield.checkAllowance(depositBody);
137
+ if (allowance.ok && !allowance.value.valid) {
138
+ const plan = await sodax.api.leverageYield.approve(depositBody);
139
+ if (!plan.ok) return;
140
+ const { tx, resetTx } = plan.value; // ApproveResponseV2
141
+ // `resetTx` appears only for an input token of the 2017 TetherToken lineage, which rejects an
142
+ // allowance change from one non-zero value to another: broadcast AND MINE it before `tx`, or the
143
+ // approve reverts. In @sodax/dapp-kit, useLeverageYieldApiApproveAndBroadcast owns that ordering.
144
+ }
145
+ ```
146
+
147
+ ### Submit tx + poll status
148
+
149
+ ```ts
150
+ // `intent` here is the IntentRequestV2 (bigint fields) you hold from createDepositIntent/createWithdrawIntent.
151
+ // `LeverageYieldSubmitTxRequestV2` is the swaps body PLUS a required `operation` discriminator, which the
152
+ // backend needs to record the queued row as a vault deposit or withdrawal.
153
+ const submit = await sodax.api.leverageYield.submitTx({
154
+ txHash, srcChainKey, walletAddress, intent,
155
+ relayData: relayData.payload, // string — the payload, not the RelayExtraData object
156
+ operation: 'deposit', // required: 'deposit' | 'withdraw'
157
+ });
158
+ if (!submit.ok) return;
159
+
160
+ // Both txHash AND srcChainKey are required by the status endpoint.
161
+ const status = await sodax.api.leverageYield.getSubmitTxStatus({ txHash, srcChainKey });
162
+ // A vault swap IS a solver swap, so terminal success is 'solved' — NOT the bridge API's 'executed'.
163
+ if (status.ok && status.value.data.status === 'solved') { /* settled */ }
164
+ // Lifecycle: 'pending' → 'relaying' → 'relayed' → 'posting_execution' → 'solved' | 'failed'.
165
+ // A set `abandonedAt` is terminal too, even while `status` is still non-terminal.
166
+ ```
167
+
168
+ ## Status fields — three distinct `status` values (don't conflate)
169
+
170
+ | Call | Field | Type | Values |
171
+ |---|---|---|---|
172
+ | `getStatus` | `StatusResponseV2.status` | **number** (`SwapIntentStatusCodeV2`) | `-1` NOT_FOUND · `1` NOT_STARTED_YET · `2` STARTED_NOT_FINISHED · `3` SOLVED (terminal) · `4` FAILED (terminal). `fillTxHash` is set only when `status === 3`. |
173
+ | `submitTx` | `SubmitTxResponseV2.data.status` | string | `'inserted'` (new) or `'duplicate'` (already submitted — submit-tx is idempotent on `(txHash, srcChainKey)`). |
174
+ | `getSubmitTxStatus` | `SubmitTxStatusResponseV2.data.status` | string | `'pending'` / `'relaying'` / `'relayed'` / `'posting_execution'` / `'posted_execution'` / `'solved'` / `'failed'` (`'solved'` / `'failed'` terminal, as for swaps — `'executed'` is the *bridge* terminal state). A set `abandonedAt` is terminal too. `data.operation` echoes `'leverage_deposit'` / `'leverage_withdraw'` (`SubmitTxOperationV2`). |
175
+
176
+ `getStatus` reports the **solver** intent status as a numeric code (shared with the Swaps API —
177
+ `SwapIntentStatusCodeV2`); the two submit-tx calls report **string** statuses. They are unrelated — don't
178
+ treat one as the other.
179
+
180
+ ## Per-call overrides
181
+
182
+ Every method accepts a trailing `RequestOverrideConfig` to redirect a single call to a different host or
183
+ attach request-specific headers (auth, tracing), overriding the service config:
184
+
185
+ ```ts
186
+ await sodax.api.leverageYield.getVaults({ baseURL: 'https://staging.example/v1', headers: { 'X-Trace': 'abc' } });
187
+ ```
188
+
189
+ ## Custom endpoint for the leverage-yield API
190
+
191
+ The leverage-yield endpoints are `/leverage-yield/*` sub-paths under the same base URL as
192
+ `sodax.backendApi`, and the client shares the **base** backend-API config — there is **no** dedicated
193
+ leverage-yield slice on `ApiConfig` (unlike swaps, which has `swapsApiConfig`). So the flat
194
+ `BaseApiConfig` (or the `baseApiConfig` slice of `CustomApiConfig`) drives it:
195
+
196
+ ```ts
197
+ // The gateway ROOT — the client appends `/leverage-yield/*` itself. A legacy `/be`-suffixed value (the
198
+ // data API's own mount) is trimmed back to the root with a warning, configured or per-call.
199
+ const sodax = new Sodax({ api: { baseURL: 'https://api.example/v1' } });
200
+ ```
201
+
202
+ To send a single leverage-yield call elsewhere, use the per-call `RequestOverrideConfig` above. See
203
+ [`backend-api.md`](backend-api.md) § "Custom backend" and [`../architecture.md`](../architecture.md).
204
+
205
+ ## Backend submit-tx flow (SDK option)
206
+
207
+ Opting into `new Sodax({ leverageYield: { useBackendSubmitTx: true } })` routes the **feature
208
+ service** (`sodax.leverageYield.vaultSwap`) through this client's `submitTx` + `getSubmitTxStatus` (relay +
209
+ post-execution server-side), polling until `'solved'` and falling back to the client-side relay on any
210
+ non-success — the leverage-yield mirror of `swaps.useBackendSubmitTx`, except that it defaults **off**.
211
+ Read the effective value on `sodax.config.leverageYieldUseBackendSubmitTx`. `timeout` is a per-attempt
212
+ budget: the backend attempt gets it and the fallback relay gets a fresh one. See
213
+ [`leverage-yield.md`](leverage-yield.md).
214
+
215
+ ## Error handling
216
+
217
+ ```ts
218
+ const r = await sodax.api.leverageYield.getDepositQuote(body);
219
+ if (!r.ok) {
220
+ // r.error: SodaxError<'EXTERNAL_API_ERROR'> — feature: 'backend', context.api: 'leverageYield',
221
+ // context.endpoint: '/leverage-yield/quote/deposit'. The transport failure (HTTP_REQUEST_FAILED /
222
+ // REQUEST_TIMEOUT / a shape-validation issue) is on r.error.cause.
223
+ // A non-2xx also lifts its status onto r.error.context.status, so isAuthFailure(r.error) is true for
224
+ // a 401/403 — a rejected key is terminal, so stop rather than retry.
225
+ return;
226
+ }
227
+ ```
228
+
229
+ ## Cross-references
230
+
231
+ - `sodax.leverageYield` (the `LeverageYieldService` orchestrator that builds/executes vault swaps end-to-end): [`leverage-yield.md`](leverage-yield.md). The API client here is the lower-level HTTP surface; the orchestrator is the higher-level flow.
232
+ - `sodax.api.swaps` (the sibling Swaps API client — shares the intent-relay/gas/fee/submit-tx wire shapes): [`swaps-api.md`](swaps-api.md).
233
+ - `BackendApiService` (the sibling client for intent/orderbook/money-market reads): [`backend-api.md`](backend-api.md).
234
+ - Error model context fields: [`../reference/error-codes.md`](../reference/error-codes.md).
@@ -4,6 +4,8 @@ Leveraged-yield ERC-4626 vaults on the Sonic hub. A vault loops supply → borro
4
4
 
5
5
  Access: `sodax.leverageYield`. Service class: `LeverageYieldService`. Feature tag for errors: `'leverageYield'`.
6
6
 
7
+ > **Backend HTTP client:** for the typed `sodax.api.leverageYield` client that calls the backend Leverage Yield API v2 directly (vault reads, deposit/withdraw quotes + intents, submit-tx), see [`leverage-yield-api.md`](leverage-yield-api.md). Opting into `new Sodax({ leverageYield: { useBackendSubmitTx: true } })` routes this service's `vaultSwap` through that client's submit-tx flow (with client-side fallback).
8
+
7
9
  ## How it works
8
10
 
9
11
  - 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`.
@@ -0,0 +1,77 @@
1
+ ---
2
+ name: sodax-sdk-leverage-yield-api
3
+ description: 'Granular skill for the @sodax/sdk v2 Leverage Yield API client — `sodax.api.leverageYield` (class LeverageYieldApiService), a typed HTTP client for the backend Leverage Yield API v2 (`/leverage-yield/*`, 33 endpoints: vault registry, vault reads (asset/position/APR/effective-APR/LSD-APR/total-assets/previews/share-balance/max-withdraw), deposit & withdraw quote, deadline, allowance/approve, create-deposit-intent & create-withdraw-intent, intent submit/status/cancel/hash/packet/extra-data/fill/get, gas estimate, partner/solver fees, submit-tx + status). Every method returns Promise<Result<T>>, never throws, and validates the response. Use when the task calls the leverage-yield backend directly (e.g. "sodax.api.leverageYield", "leverage vault APR from the backend", "vault position from the API", "leverage-yield deposit quote", "createDepositIntent via the backend API", "leverage-yield API v2"). For the higher-level end-to-end vault-swap orchestrator use the `leverage-yield` skill instead. Skill links into the parent sodax-sdk knowledge tree.'
4
+ ---
5
+
6
+ # Leverage Yield API (Core SDK granular skill)
7
+
8
+ Granular skill for `sodax.api.leverageYield` (class `LeverageYieldApiService`) — the typed HTTP client for
9
+ the backend **Leverage Yield API v2** (`/leverage-yield/*`). `sodax.api` is an alias for `sodax.backendApi`;
10
+ `.leverageYield` is the leverage-yield client. 33 endpoints, one method each; every method returns
11
+ `Promise<Result<T>>` (never throws) and validates the response. Errors carry `feature: 'backend'`,
12
+ `context.api: 'leverageYield'`, `context.endpoint`.
13
+
14
+ A leverage-yield deposit/withdraw **is** an intent-based swap (the vault's `lsoda*` share token is
15
+ solver-tradeable), so the intent-relay / gas / fee / submit-tx endpoints share the Swaps API wire shapes —
16
+ this is the leverage-yield sibling of the [`swaps-api`](../swaps-api/SKILL.md) skill.
17
+
18
+ > Lower-level than `sodax.leverageYield`: this is the raw backend HTTP surface. For the end-to-end
19
+ > build→relay→post-execution vault swap orchestrator, use the [`leverage-yield`](../leverage-yield/SKILL.md) skill.
20
+
21
+ ## Step 1 — Clarify with user before coding
22
+
23
+ 1. **Which endpoint(s)?** Vault registry · vault reads (asset/position/APR/effective-APR/LSD-APR/total-assets/
24
+ previews/share-balance/max-withdraw) · deposit/withdraw quote · deadline · allowance/approve ·
25
+ create-deposit-intent / create-withdraw-intent · intent lifecycle (submit/status/cancel/hash/packet/
26
+ extra-data/fill/get) · gas/fees · submit-tx/status.
27
+ 2. **Orchestrator or raw API?** If the user just wants "deposit into / withdraw from a leverage vault",
28
+ prefer `sodax.leverageYield` (the `leverage-yield` skill). Use `sodax.api.leverageYield` when they need a
29
+ single backend call (a vault APR, a position read, a deposit quote, a status poll) or are building their
30
+ own flow.
31
+ 3. **Deposit vs withdraw?** Create-intent is split: `createDepositIntent` (any token → `lsoda*`, needs a
32
+ spoke allowance) vs `createWithdrawIntent` (`lsoda*` → any token, hub-wallet swap, no spoke allowance).
33
+
34
+ ## Integration workflow
35
+
36
+ 1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
37
+ 2. [`../integration/knowledge/features/leverage-yield-api.md`](../integration/knowledge/features/leverage-yield-api.md) — the full 33-endpoint client: signatures, wire shapes (bigint vs decimal string), common call shapes (vault reads, deposit quote, create-intent, submit-tx + status), per-call overrides, custom endpoint, the `useBackendSubmitTx` service option.
38
+ 3. For the end-to-end vault-swap flow that wraps these calls → [`../integration/knowledge/features/leverage-yield.md`](../integration/knowledge/features/leverage-yield.md); for the intent-sibling swaps client → [`../integration/knowledge/features/swaps-api.md`](../integration/knowledge/features/swaps-api.md).
39
+ 4. Errors are `Result<T, SodaxError<'EXTERNAL_API_ERROR'>>` → [`../integration/knowledge/recipes/result-and-errors.md`](../integration/knowledge/recipes/result-and-errors.md) and [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
40
+
41
+ ### Leverage-Yield-API-specific anti-patterns
42
+
43
+ - **`try/catch` for failures.** Every method returns `Result<T>` — branch on `result.ok`. `catch` won't fire for HTTP/timeout/validation failures.
44
+ - **Passing the `RelayExtraData` object** to `submitTx`'s `relayData`. The field is a `string` — pass `relayData.payload`.
45
+ - **Omitting `operation` on `submitTx`.** `LeverageYieldSubmitTxRequestV2` is the swaps body PLUS a required `operation: 'deposit' | 'withdraw'` — the backend records the queued row from it.
46
+ - **Polling for `'executed'`.** A vault swap IS a solver swap, so terminal success is `'solved'` (`'executed'` is the *bridge* API's terminal state). A set `abandonedAt` is terminal too.
47
+ - **Broadcasting `approve`'s `tx` without its `resetTx`.** `ApproveResponseV2` is `{ tx, resetTx? }`; a guarded input token needs `resetTx` MINED first or the approve reverts. In `@sodax/dapp-kit`, prefer `useLeverageYieldApiApproveAndBroadcast`, which owns that ordering.
48
+ - **Stringifying `intent` numerics yourself.** `IntentRequestV2` fields are `bigint`; the client serializes them to decimal strings — pass the bigint intent through as-is.
49
+ - **Checking allowance for a withdraw.** `createWithdrawIntent` is a hub-wallet swap (spends `lsoda*` from the hub wallet) — there is no spoke allowance step. `checkAllowance`/`approve` take the **deposit** params only.
50
+ - **Calling `getSubmitTxStatus` with only `txHash`.** Both `txHash` AND `srcChainKey` are required.
51
+ - **Confusing `sodax.api.leverageYield` with `sodax.leverageYield`.** The former is the backend HTTP client; the latter is the on-chain vault-swap orchestrator.
52
+
53
+ ## Migration workflow (v1 → v2)
54
+
55
+ The typed `sodax.api.leverageYield` client is **v2-new** — leverage yield itself has no v1 equivalent, so
56
+ there is nothing to port. The intent-relay / submit-tx request shapes it shares with swaps are covered in
57
+ the swap + backend-api migration docs if you need the deltas:
58
+
59
+ 1. [`../migration-v1-to-v2/knowledge/features/swap.md`](../migration-v1-to-v2/knowledge/features/swap.md) — create-intent / submit-tx request-shape changes (`srcChainId` → `srcChainKey`, `relayData` object → string, bigint intent).
60
+ 2. [`../migration-v1-to-v2/knowledge/features/backend-api.md`](../migration-v1-to-v2/knowledge/features/backend-api.md) — the `Result`-wrapping HTTP-client contract.
61
+
62
+ ## Verification
63
+
64
+ 1. `pnpm tsc --noEmit` clean.
65
+ 2. Every `await sodax.api.leverageYield.<method>(...)` call site has `if (!result.ok)`.
66
+ 3. `submitTx.relayData` is `relayData.payload` (string), `submitTx` carries `operation`, and `getSubmitTxStatus` passes both `txHash` and `srcChainKey`.
67
+ 4. Submit-tx status polling stops on `'solved'` / `'failed'` / `abandonedAt` — not on `'executed'`.
68
+ 5. Intent-bearing bodies pass the `bigint` `IntentRequestV2` through unmodified (no manual `.toString()`).
69
+ 6. Allowance/approve are used only for the deposit path (withdraw is a hub-wallet swap), and a returned `resetTx` is broadcast and mined before `tx`.
70
+
71
+ ## Related granular skills (same family)
72
+
73
+ - [`../leverage-yield/SKILL.md`](../leverage-yield/SKILL.md) — the end-to-end vault-swap orchestrator (`sodax.leverageYield`) that wraps these backend calls.
74
+ - [`../swaps-api/SKILL.md`](../swaps-api/SKILL.md) — the intent-sibling Swaps API client (`sodax.api.swaps`), same intent-relay/gas/fee/submit-tx wire shapes.
75
+ - [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — the sibling `sodax.backendApi` read client (intent / orderbook / money-market reads + config).
76
+
77
+ For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
@@ -113,7 +113,7 @@ These v1 names still ship through `@sodax/sdk` (re-exported from `@sodax/types`)
113
113
  |---|---|---|
114
114
  | `moneyMarketSupportedTokens[chainId]` | Still exported (`packages/types/src/moneyMarket/moneyMarket.ts`) | `sodax.moneyMarket.getSupportedTokensByChainId(chainKey)` |
115
115
  | `Object.entries(moneyMarketSupportedTokens)` (walk pattern) | Const still exported | `sodax.moneyMarket.getSupportedTokens()` (returns `Record<SpokeChainKey, XToken[]>`) |
116
- | `SodaTokens` registry (vault-validation) | Still exported (`packages/types/src/chains/tokens.ts`) | `sodax.config.getMoneyMarketReserveAssets()` or `sodax.moneyMarket.getSupportedReserves()` |
116
+ | `SodaTokens` (hub-vault registry — feature-neutral, **not** the reserve list) | Still exported (`packages/types/src/chains/tokens.ts`) | `sodax.config.getMoneyMarketReserveAssets()` or `sodax.moneyMarket.getSupportedReserves()` for reserves; `sodax.config.getSupportedSwapTokensByChainId('sonic')` for swaps |
117
117
  | `swapSupportedTokens[chainId]` (v1 had no `solverSupportedTokens`) | Still exported (`packages/types/src/swap/swap.ts`) | `sodax.config.getSupportedSwapTokensByChainId(chainKey)` |
118
118
  | `getSupportedSolverTokens(chainId)` (free function) | Still exported (`packages/types/src/swap/swap.ts`) | `sodax.config.getSupportedSwapTokensByChainId(chainKey)` |
119
119
  | `supportedSpokeChains` (`SpokeChainKey[]`) | Still exported (`packages/types/src/chains/chains.ts`) | `sodax.config.isValidSpokeChainKey(chainKey)` for validation, or read `sodaxConfig.chains` at module scope |
@@ -30,7 +30,7 @@ Pair: [`features/money-market.md`](../../../integration/knowledge/features/money
30
30
 
31
31
  - `moneyMarketSupportedTokens` — `Record<SpokeChainKey, XToken[]>` global. Use `sodax.moneyMarket.getSupportedTokensByChainId(chainKey)` / `getSupportedTokens()`.
32
32
  - `hubAssets` — vault address lookup global. Use `XToken.vault` / `XToken.hubAsset` directly.
33
- - `SodaTokens` — vault-validation registry. Use `sodax.config.getMoneyMarketReserveAssets()`.
33
+ - `SodaTokens` — hub-vault registry. It is feature-neutral: a vault listed there is not necessarily a money-market reserve (the Robinhood tokenized equities are swap-only, for example). Never derive reserve support from it — use `sodax.config.getMoneyMarketReserveAssets()`.
34
34
  - `MoneyMarketError<MoneyMarketErrorCode>` and `isMoneyMarketError` — replaced by `SodaxError<C>` + `isSodaxError(e) && e.feature === 'moneyMarket'`.
35
35
 
36
36
  ### v1 → v2 error code crosswalk (money-market-specific)
@@ -32,6 +32,7 @@ Granular skill for `EvmWalletProvider` — the low-level EVM wallet for backend
32
32
  - **Passing `publicClient` / `walletClient` / `transport` defaults in browser-extension mode.** They're ignored (provider logs a one-time warn); supply them only in PK mode.
33
33
  - **Adding `viem` as a direct dep** when `WalletClient` / `PublicClient` etc. re-export from `@sodax/wallet-sdk-core`.
34
34
  - **Assuming nonce management.** There is none — fire parallel sends and you collide; set `defaults.sendTransaction.nonce` or per-call `nonce`.
35
+ - **Skipping `expectedChainId` on chain-specific sends.** Without it the tx goes to whatever chain the wallet is on; with it a mismatch throws and nothing is sent.
35
36
 
36
37
  ## Migration workflow (port v1 → v2)
37
38
 
@@ -67,7 +67,7 @@ type EvmWalletDefaults = {
67
67
  | Method | Signature | Returns | Default slice merged |
68
68
  |---|---|---|---|
69
69
  | `getWalletAddress` | `() => Promise<Address>` | viem `Address` (`` `0x${string}` ``) | — |
70
- | `sendTransaction` | `(txData: EvmRawTransaction, options?: EvmSendTransactionPolicy) => Promise<Hash>` | viem `Hash` | `defaults.sendTransaction` |
70
+ | `sendTransaction` | `(txData: EvmRawTransaction, options?: EvmSendTransactionPolicy & EvmSendTransactionOptions) => Promise<Hash>` | viem `Hash` | `defaults.sendTransaction` |
71
71
  | `waitForTransactionReceipt` | `(txHash: Hash, options?: EvmWaitForTransactionReceiptPolicy) => Promise<EvmRawTransactionReceipt>` | bigint-stringified receipt | `defaults.waitForTransactionReceipt` |
72
72
 
73
73
  The serialised receipt converts all `bigint` fields to `string` so it can be `JSON.stringify`'d safely. This is enforced at the type level — `EvmRawTransactionReceipt` (from `@sodax/types`) is the stringified shape.
@@ -90,6 +90,8 @@ The serialised receipt converts all `bigint` fields to `string` so it can be `JS
90
90
  - **`getEvmViemChain` is exhaustive.** If `@sodax/types` adds a new `EvmChainKey`, this function fails to typecheck until the case is added — by design.
91
91
  - **HyperEVM is defined inside this package.** `viem/chains` does not ship a HyperEVM config; `wallet-providers/evm/EvmWalletProvider.ts` exports `hyper` via `defineChain`. You shouldn't need it directly — `getEvmViemChain(ChainKeys.HYPEREVM_MAINNET)` returns it.
92
92
  - **`rpcUrl` falls back to the viem chain's first public RPC.** Fine for testing — replace with a private RPC for production.
93
+ - **Chain binding is opt-in.** Pass `options.expectedChainId` (`getEvmViemChain(chainKey).id`) and the provider refuses to send when the wallet's active chain differs. The SDK passes it on every signed send it owns: spoke/hub deposits and messages, signed ERC-20 approvals (reset leg included), and the hub-scoped vault, partner, BALN, `Permit2Service` and `Erc4626Service` sends — the last two are bound to Sonic, so calling them with a wallet on another EVM network now throws instead of broadcasting there.
94
+ - **The chain check fails closed.** `eth_chainId` is normalised to a plain `number` before a strict compare; a mismatch or malformed wallet response throws and nothing is sent.
93
95
  - **No nonce management.** The provider does not auto-increment / serialise sends. If you fire multiple txs in parallel from the same account, manage nonces yourself via `defaults.sendTransaction.nonce` or per-call `options.nonce`.
94
96
 
95
97
  ---