@sodax/skills 2.2.0-rc.5 → 2.2.0-rc.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/package.json +1 -1
  2. package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +2 -2
  3. package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +9 -8
  4. package/skills/sodax-dapp-kit/integration/knowledge/features/bridge.md +3 -0
  5. package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +71 -4
  6. package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +1 -1
  7. package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +2 -1
  8. package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +2 -2
  9. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +166 -1
  10. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +7 -5
  11. package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +5 -3
  12. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +22 -1
  13. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +1 -1
  14. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +1 -1
  15. package/skills/sodax-sdk/SKILL.md +3 -3
  16. package/skills/sodax-sdk/backend-api/SKILL.md +1 -1
  17. package/skills/sodax-sdk/bridge-api/SKILL.md +2 -2
  18. package/skills/sodax-sdk/integration/knowledge/architecture.md +1 -1
  19. package/skills/sodax-sdk/integration/knowledge/features/README.md +3 -3
  20. package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +1 -1
  21. package/skills/sodax-sdk/integration/knowledge/features/bridge-api.md +10 -3
  22. package/skills/sodax-sdk/integration/knowledge/features/bridge.md +4 -0
  23. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield-api.md +13 -8
  24. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +194 -3
  25. package/skills/sodax-sdk/integration/knowledge/features/swap.md +24 -5
  26. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +2 -2
  27. package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -0
  28. package/skills/sodax-sdk/integration/knowledge/recipes/manual-submit-tx-with-fallback.md +184 -0
  29. package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +1 -1
  30. package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -1
  31. package/skills/sodax-sdk/leverage-yield/SKILL.md +25 -1
  32. package/skills/sodax-sdk/leverage-yield-api/SKILL.md +2 -2
  33. package/skills/sodax-sdk/swap/SKILL.md +2 -1
  34. package/skills/sodax-sdk/swaps-api/SKILL.md +2 -2
  35. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +1 -1
  36. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +2 -2
@@ -0,0 +1,184 @@
1
+ # Manual submit-tx with client-side fallback
2
+
3
+ `sodax.swaps.swap()` already does this internally: it creates the intent, tries the backend submit-tx path, and on **any** non-success falls back to the client-side relay. Prefer `swap()` unless the consumer must own each step (a bot that persists every transition, a backend with its own signing boundary, a UI that reports phases).
4
+
5
+ When they do own the steps, reproduce **both** paths. The orchestration helpers behind `swap()` are package-internal — `SwapService.submitTx` and `SwapService.fallbackSwapSteps` are private, and the attempt budget and poll loop are not exported — so the loop is hand-written from the public pieces below.
6
+
7
+ Bindings shared by every step below:
8
+
9
+ ```ts
10
+ import type { IEvmWalletProvider, SpokeChainKey } from '@sodax/sdk';
11
+
12
+ declare const evmWallet: IEvmWalletProvider;
13
+ declare const srcChainKey: SpokeChainKey; // === params.srcChainKey
14
+ declare const timeoutMs: number; // per-attempt budget, e.g. DEFAULT_RELAY_TX_TIMEOUT
15
+ ```
16
+
17
+ ## 1. Create the intent, keep all three values
18
+
19
+ ```ts
20
+ const created = await sodax.swaps.createIntent({ params, walletProvider: evmWallet });
21
+ if (!created.ok) return created;
22
+
23
+ const { tx: spokeTxHash, intent, relayData } = created.value;
24
+ ```
25
+
26
+ ## 2. Build the request
27
+
28
+ ```ts
29
+ import type { SubmitTxRequestV2 } from '@sodax/sdk';
30
+
31
+ const request: SubmitTxRequestV2 = {
32
+ txHash: spokeTxHash as string,
33
+ srcChainKey: params.srcChainKey,
34
+ walletAddress: params.srcAddress, // the SOURCE address that signed, not the destination
35
+ intent, // passes straight through from createIntent
36
+ relayData: relayData.payload, // the hex STRING, not the { address, payload } object
37
+ };
38
+ ```
39
+
40
+ Persist `request` **before** submitting. Re-submitting the same `(txHash, srcChainKey)` is idempotent (`data.status: 'duplicate'`); never sign a second deposit to recover.
41
+
42
+ `request.intent` carries `bigint` fields (`intentId`, `inputAmount`, `minOutputAmount`, `deadline`, `srcChain`, `dstChain`), so plain `JSON.stringify(request)` THROWS — in the exact crash window this step exists to survive. Serialize them, and coerce them back on resume:
43
+
44
+ ```ts
45
+ const serialized = JSON.stringify(request, (_k, v) => (typeof v === 'bigint' ? v.toString() : v));
46
+ ```
47
+
48
+ Passing `intent` straight to `submitTx` still needs no conversion — the wire client serializes internally. Only your own storage does.
49
+
50
+ ## 3. Open the attempt budget, then submit
51
+
52
+ The attempt starts **before** the POST — the submit draws on the same budget as the poll, so a stalled POST costs the attempt instead of silently extending it. Cap every request at the budget left, never above the service's own timeout.
53
+
54
+ ```ts
55
+ const serviceTimeoutMs = sodax.api.swaps.getTimeout();
56
+ const attemptDeadline = Date.now() + timeoutMs;
57
+
58
+ const remaining = () => Math.max(0, attemptDeadline - Date.now());
59
+ const requestTimeout = (): number | null => {
60
+ const capped = Math.min(remaining(), serviceTimeoutMs);
61
+ return capped > 0 ? capped : null; // null → issue no request at all
62
+ };
63
+
64
+ const submitBudget = requestTimeout();
65
+ if (submitBudget === null) return fallback();
66
+
67
+ const submitted = await sodax.api.swaps.submitTx(request, { timeout: submitBudget });
68
+
69
+ // Two distinct arms — the reason lives in a different place on each.
70
+ if (!submitted.ok) return fallback(); // transport: submitted.error.code
71
+ if (!submitted.value.success) return fallback(); // 200 not queued: submitted.value.data.message
72
+ ```
73
+
74
+ Do **not** call `verifyTxHash` before this. The backend verifies itself, so a client-side confirmation wait only delays every backend success. Verification belongs to the fallback.
75
+
76
+ ## 4. Poll until `solved`
77
+
78
+ Same budget, same cap per request, and no sleep the attempt cannot outlast — that wait only delays the fallback.
79
+
80
+ ```ts
81
+ import { isAuthFailure } from '@sodax/sdk';
82
+ import type { Result, SubmitTxStatusQueryV2, SwapResponse } from '@sodax/sdk';
83
+
84
+ const query: SubmitTxStatusQueryV2 = { txHash: spokeTxHash as string, srcChainKey };
85
+ const intervalMs = 1_000;
86
+
87
+ for (let budget = requestTimeout(); budget !== null; budget = requestTimeout()) {
88
+ const snapshot = await sodax.api.swaps.getSubmitTxStatus(query, { timeout: budget });
89
+
90
+ if (snapshot.ok) {
91
+ const { status, result, abandonedAt } = snapshot.value.data;
92
+ // Terminal success needs BOTH fields.
93
+ if (status === 'solved' && result?.dstIntentTxHash && result.intent_hash) {
94
+ const value: SwapResponse = {
95
+ solverExecutionResponse: { answer: 'OK', intent_hash: result.intent_hash as `0x${string}` },
96
+ intent,
97
+ intentDeliveryInfo: {
98
+ srcChainKey,
99
+ srcTxHash: spokeTxHash as string,
100
+ srcAddress: params.srcAddress,
101
+ dstChainKey: params.dstChainKey,
102
+ dstTxHash: result.dstIntentTxHash,
103
+ dstAddress: params.dstAddress,
104
+ },
105
+ };
106
+ return { ok: true, value } satisfies Result<SwapResponse>;
107
+ }
108
+ if (status === 'failed' || abandonedAt) break; // terminal failure
109
+ // pending | relaying | relayed | posting_execution | posted_execution → keep polling
110
+ } else if (isAuthFailure(snapshot.error)) {
111
+ break; // a rejected API key cannot become success by waiting
112
+ }
113
+
114
+ if (remaining() <= intervalMs) break;
115
+ await new Promise(r => setTimeout(r, intervalMs));
116
+ }
117
+
118
+ return fallback(); // every exit other than `solved` is a non-success
119
+ ```
120
+
121
+ ## 5. Fallback — the client-side relay
122
+
123
+ Returns the **same** `SwapResponse` as the backend path, so callers handle completion through one contract whichever path ran — as `swap()` does.
124
+
125
+ ```ts
126
+ import { relayTxAndWaitPacket, RELAY_FALLBACK_FLOOR_MS, isHubChainKeyType } from '@sodax/sdk';
127
+ import type { Result, SwapResponse } from '@sodax/sdk';
128
+
129
+ async function fallback(): Promise<Result<SwapResponse>> {
130
+ const verified = await sodax.spoke.verifyTxHash({ txHash: spokeTxHash as string, chainKey: srcChainKey });
131
+ if (!verified.ok) return verified;
132
+
133
+ let hubTxHash: string;
134
+ if (isHubChainKeyType(srcChainKey)) {
135
+ hubTxHash = spokeTxHash as string; // source IS the hub — nothing to relay
136
+ } else {
137
+ const packet = await relayTxAndWaitPacket({
138
+ srcTxHash: spokeTxHash as string,
139
+ data: relayData, // the OBJECT here, not the payload string
140
+ chainKey: srcChainKey,
141
+ relayerApiEndpoint: sodax.swaps.relayerApiEndpoint,
142
+ timeout: Math.max(timeoutMs, RELAY_FALLBACK_FLOOR_MS), // a FRESH budget
143
+ });
144
+ if (!packet.ok) return packet;
145
+ hubTxHash = packet.value.dst_tx_hash;
146
+ }
147
+
148
+ const posted = await sodax.swaps.postExecution({ intent_tx_hash: hubTxHash as `0x${string}` });
149
+ if (!posted.ok) return posted;
150
+
151
+ return {
152
+ ok: true,
153
+ value: {
154
+ solverExecutionResponse: posted.value,
155
+ intent,
156
+ intentDeliveryInfo: {
157
+ srcChainKey,
158
+ srcTxHash: spokeTxHash as string,
159
+ srcAddress: params.srcAddress,
160
+ dstChainKey: params.dstChainKey,
161
+ dstTxHash: hubTxHash,
162
+ dstAddress: params.dstAddress,
163
+ },
164
+ },
165
+ };
166
+ }
167
+ ```
168
+
169
+ ## Rules
170
+
171
+ - **Two budgets, never one.** The backend attempt gets a timeout; the fallback relay gets a *fresh* one. A single shared deadline leaves the fallback only what the backend did not spend — that is how a relay that needs longer ends in a timeout.
172
+ - **Falling back is safe.** Re-relaying and re-posting an already-processed swap is idempotent: the relay deduplicates and returns the existing `executed` packet, and the solver re-affirms the intent rather than filling twice. It is also load-bearing — the backend keeps processing after the poll gives up, so the two relays can race.
173
+ - **Solana / Bitcoin need the exact `relayData` bytes** — those deposits commit only a hash of the payload on-chain. If the runtime value is gone, recover it with `sodax.swaps.getIntentSubmitTxExtraData({ txHash })`, where `txHash` is the **hub-chain** tx hash (it reads the intent off the hub) — not the source-chain `spokeTxHash` used elsewhere here. From an `Intent` you already hold, `sodax.swaps.reconstructRelayData(intent)` derives the same bytes offline.
174
+ - **Read status with `getDetailedStatus`**, which routes between the backend record and the solver — do not hand-roll that fallback too.
175
+ - Opting out entirely is a config flag, not hand-written code: `new Sodax({ swaps: { useBackendSubmitTx: false } })` makes `swap()` take the client-side path only.
176
+
177
+ ---
178
+
179
+ ## Cross-references
180
+
181
+ - [`README.md`](README.md) — recipe index.
182
+ - [`../features/swap.md`](../features/swap.md) — `SwapService` surface, action params, error codes.
183
+ - [`result-and-errors.md`](result-and-errors.md) — branching on `result.ok` and `(feature, code)`.
184
+ - [`backend-server-init.md`](backend-server-init.md) — bot / partner-backend setup around this flow.
@@ -162,7 +162,7 @@ Both follow the same shape: action methods get the full exec union (`'EXECUTION_
162
162
 
163
163
  ### Backend / Swaps API (`feature: 'backend'`)
164
164
 
165
- `BackendApiService` (`sodax.backendApi`) and the Swaps API v2 client (`sodax.api.swaps`) are the HTTP-client layer — not domain features. Every method returns `Result<T, SodaxError<'EXTERNAL_API_ERROR'>>` with `context.endpoint`, and the transport failure (timeout / non-2xx / response-shape mismatch) preserved on `error.cause`. `context.api` distinguishes the two clients: `'backend'` for `BackendApiService`, `'swaps'` for the `sodax.api.swaps` client.
165
+ `BackendApiService` (`sodax.backendApi`) and the Swaps API client (`sodax.api.swaps`) are the HTTP-client layer — not domain features. Every method returns `Result<T, SodaxError<'EXTERNAL_API_ERROR'>>` with `context.endpoint`, and the transport failure (timeout / non-2xx / response-shape mismatch) preserved on `error.cause`. `context.api` distinguishes the two clients: `'backend'` for `BackendApiService`, `'swaps'` for the `sodax.api.swaps` client.
166
166
 
167
167
  ### Leverage Yield (`feature: 'leverageYield'`)
168
168
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  Import everything from `@sodax/sdk`. The barrel re-exports the entire `@sodax/types` surface — you don't need a separate `@sodax/types` dependency.
4
4
 
5
- `sodax.api` is an alias for `sodax.backendApi`; `sodax.api.swaps` is the typed Swaps API v2 client (`SwapsApiService`) — see [`../features/swaps-api.md`](../features/swaps-api.md).
5
+ `sodax.api` is an alias for `sodax.backendApi`; `sodax.api.swaps` is the typed Swaps API client (`SwapsApiService`) — see [`../features/swaps-api.md`](../features/swaps-api.md).
6
6
 
7
7
  ### Top-level exports
8
8
 
@@ -15,6 +15,14 @@ import {
15
15
  type SodaxDefaultConfig, // static data contract the backend serves / defaults are built from
16
16
  type DeepPartial,
17
17
 
18
+ // Release identity — see "Config version" below
19
+ CONFIG_VERSION,
20
+ SDK_VERSION,
21
+ configVersionFor,
22
+ formatConfigVersion,
23
+ parseConfigVersion,
24
+ type ParsedConfigVersion,
25
+
18
26
  // Logging (see recipes/logging.md)
19
27
  type SodaxLogger,
20
28
  type SodaxLoggerOption,
@@ -215,6 +223,34 @@ This is a partial list — see `src/index.ts` of the published tarball for the a
215
223
  ---
216
224
 
217
225
 
226
+ ## Config version
227
+
228
+ `CONFIG_VERSION` identifies the SDK release a SODAX config belongs to. The backend serves this same
229
+ constant from the `@sodax/sdk` release it has installed, so comparing the two answers *are the SDK and
230
+ the API on the same release?* It is derived from the package version:
231
+ `major * 1e6 + minor * 1e4 + patch * 100 + (rc ?? 99)`, where the `99` rc slot means "stable".
232
+
233
+ ```ts
234
+ import { CONFIG_VERSION, SDK_VERSION, configVersionFor, formatConfigVersion, parseConfigVersion } from '@sodax/sdk';
235
+
236
+ SDK_VERSION; // '2.0.0-rc.17' — computed from CONFIG_VERSION, so it cannot go stale
237
+ formatConfigVersion(2_020_099); // '2.2.0'
238
+ parseConfigVersion(2_020_006); // { major: 2, minor: 2, patch: 0, rc: 6 }
239
+ configVersionFor('2.2.0'); // 2_020_099
240
+ ```
241
+
242
+ **All three helpers are total** — they return `null` rather than throwing, for anything outside the
243
+ encoding: an out-of-grammar version (`configVersionFor('2.3.0-beta.1')`), a field out of range
244
+ (`configVersionFor('2.2.100')` — minor and patch cap at 99, rc at 98, major at 1..99), or a number that
245
+ is not a config version at all (`parseConfigVersion(235)`, a legacy counter value). Handle the `null`;
246
+ do not assume a value came back.
247
+
248
+ `rc` is `null` for a stable release. `rc: 0` is legal and falsy, so compare against `null` rather than
249
+ testing truthiness.
250
+
251
+ Do not unpack the integer by hand, and do not write your own copy of the formula — the field widths are
252
+ part of the contract and are enforced at release time.
253
+
218
254
  ## Cross-references
219
255
 
220
256
  - [`README.md`](README.md) — reference index.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sodax-sdk-leverage-yield
3
- 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.'
3
+ description: 'Granular skill for the @sodax/sdk v2 leverage-yield feature only, covering BOTH products on LeverageYieldService: (1) leveraged-yield ERC-4626 vaults on Sonic — deposit any token → lsoda* shares, withdraw shares → any token (solver-tradeable intent swaps), createVaultIntent/vaultSwap/notifySolver, approve/isAllowanceValid, and reads (getApr, getEffectiveApr, getPosition, getTotalAssets, preview*, getMaxWithdraw*, getShareBalance*, listVaults); and (2) LEVERAGE POSITIONS — one owner-controlled AAVE account per position cloned by LeveragePositionFactory, via openLeveragePosition / submitLeveragePositionIntent / runLeveragePositionOperation, the openPosition / openPositionFromDebtToken / operatePosition low-level pair, position reads (listPositions, listPositionsForUser, getPositionInfo, getPositionAccount, getPositionCollateralBalance, getPositionPendingState, predictPosition), approvePositionFunding, and leg sizing with sizeLeverageBorrow / projectLeverageLeg / getPositionLegQuote. Use when the task is leverage-yield vaults (e.g. "deposit into a leverage vault", "withdraw lsoda shares", "vault APR / effective APR", "lsoda share balance") OR leverage positions (e.g. "open a leverage position", "adjust / increase / decrease leverage", "close a leveraged position", "position health factor / LTV", "size borrowAmount and minCollateralOut", "leveraged long with my own AAVE account"). New in v2 — integration only, no v1 migration path. Links into the parent sodax-sdk knowledge tree. For React dapps, prefer sodax-dapp-kit.'
4
4
  license: MIT
5
5
  metadata:
6
6
  version: '0.0.1'
@@ -13,11 +13,19 @@ Granular skill for `LeverageYieldService` — `sodax.leverageYield`. Feature tag
13
13
 
14
14
  ## Step 1 — Clarify with user before coding
15
15
 
16
+ 0. **Vault or leverage position?** Ask this first — they share the service and nothing else. A **vault** is one pooled ERC-4626 position at a single target LTV, entered/exited as an intent swap (`deposit` / `withdraw` / `vaultSwap`). A **leverage position** is the user's own AAVE account, cloned per position, with its own eMode category and leverage tier (`openLeveragePosition` and friends). "Deposit into a leverage vault" is the first; "open a leverage position", "adjust my leverage", "close my position" is the second. If the answer is positions, jump to Step 1b.
16
17
  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.
17
18
  2. **Build vs execute.** `deposit` / `withdraw` only *build* a `LeverageYieldSwapPayload`; `vaultSwap` *executes* it end-to-end. Spread the built payload into `vaultSwap({ ...payload, walletProvider })`.
18
19
  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`.
19
20
  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).
20
21
 
22
+ ### Step 1b — leverage positions
23
+
24
+ 1. **Which operation?** It decides the method, and the choice is not stylistic. Open → `openLeveragePosition`. Leverage change (`buildAddLeverage` / `buildDecreaseLeverage`) → `submitLeveragePositionIntent`. Withdraw / settle / cancel → `runLeveragePositionOperation`. The first two report the intent; the third has nothing to report. Sending a leverage change through the route-only path leaves an intent nothing will fill, and it expires without a word — the compiler refuses it via the `PositionIntentCall` / `PositionDirectCall` brands.
25
+ 2. **Which side funds the open?** `side: 'collateral'` deposits the collateral asset. `side: 'debt'` funds with the debt token and the deposit is **not** collateral — it goes to the solver as part of the input, so the only collateral the position gets is what the solver delivers.
26
+ 3. **Have you sized the leg?** `borrowAmount` / `minCollateralOut` must come from `sizeLeverageBorrow` → `getPositionLegQuote` → `projectLeverageLeg`. Oracle parity is wrong and fails *after* the solver fills. Never hand-roll it.
27
+ 4. **Which chain?** Sonic (the hub) is the proven path. A non-hub `srcChainKey` is `@experimental`; Bitcoin is refused outright.
28
+
21
29
  ## Integration workflow
22
30
 
23
31
  1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
@@ -37,12 +45,28 @@ Granular skill for `LeverageYieldService` — `sodax.leverageYield`. Feature tag
37
45
  - **Quoting with a different `partnerFee` than the intent charges.** The fee is deducted from the input before the swap, so the quote is sized on a different net input; when the intent's fee is the larger one, the `minOutputAmount` derived from that quote can't be met and the intent never fills. Pass the same `partnerFee` to `getQuote` and to `deposit()` / `vaultSwap()`, or omit it on both.
38
46
  - **Assuming `swaps.partnerFee` monetizes vault flows.** It does not — configure `leverageYield.partnerFee` (or the global `fee`).
39
47
 
48
+ ### Leverage-position anti-patterns
49
+
50
+ - **Sizing `borrowAmount` / `minCollateralOut` from oracle prices.** The hook supplies what the solver actually paid and only then borrows against it, so the pool sees `deposit + solver output`, never `deposit × leverage`. Parity sizing is accepted, the solver fills, and the borrow then reverts with Aave `'36'` — unwinding the fill. Use `sizeLeverageBorrow` + `projectLeverageLeg` with a `getPositionLegQuote` between them, and treat `exceedsMaxLtv` as a hard gate.
51
+ - **Quoting `borrowAmount` instead of `intentInput`.** On a debt-side open the user's own contribution goes to the solver too, so quoting the borrow alone understates the input.
52
+ - **Calling `getQuote` for a position leg.** `getPositionLegQuote` names the hub reserves the intent actually swaps and quotes gross — both details a hand-rolled `getQuote` gets wrong, and both surface only as an unfillable floor. Pass the reserve **address** (`reserve.underlyingAsset`), not the reserve object.
53
+ - **Routing a leverage change through `runLeveragePositionOperation`.** It does not notify, so the intent expires unfilled. The brands refuse it at compile time — do not cast past them.
54
+ - **Treating a resolved open as an open position.** `openLeveragePosition` resolving means the intent is LIVE. Read `notified` on the value; `false` means nothing will fill it. It is deliberately not an error — retrying would open a second position.
55
+ - **Treating the transaction receipt as completion.** `addLeverage` / `decreaseLeverage` are filled by a solver afterwards; poll `getPositionPendingState`.
56
+ - **Reporting `srcChainTxHash` to `notifySolver`.** The intent exists in the **hub** transaction — `dstChainTxHash`. They are the same only on the hub.
57
+ - **Sizing a transaction from `totalCollateralBase`.** Base-currency figures are display-only; use `getPositionCollateralBalance`. An over-sized `decreaseLeverage` does not fail on submission — it reverts at fill and the intent silently expires.
58
+ - **Charging an existing position the configured fee.** `getEffectivePositionFee()` is what a NEW position would carry; an existing one's fee was fixed at creation — read `getPositionInfo`. The fee is given up on top of the solver's payment, so an exit sized at the whole collateral balance cannot settle.
59
+ - **Approving the factory.** It pulls from nobody. Funding is a transfer to `predictPosition(...)`; the one real approval has a spender that differs per chain, which `approvePositionFunding` resolves.
60
+ - **Passing an `owner`.** There is none — the factory requires `cfg.owner == msg.sender` and the caller is always the funder's own hub wallet.
61
+
40
62
  ## Verification
41
63
 
42
64
  1. `pnpm tsc --noEmit` clean.
43
65
  2. Every `await sodax.leverageYield.<method>(...)` has `if (!result.ok)`.
44
66
  3. Deposit/withdraw build a payload that is then run through `vaultSwap` (or `createVaultIntent` + relay + `notifySolver`).
45
67
  4. APR display uses `getEffectiveApr`; share/withdraw sizing from a spoke address uses the `*ForUser` reads.
68
+ 5. Positions: every `borrowAmount` / `minCollateralOut` traces back to `sizeLeverageBorrow` + `projectLeverageLeg` (never oracle parity), `exceedsMaxLtv` is checked before posting, and `notified` is read on every open / leverage change.
69
+ 6. Positions: leverage changes go through `submitLeveragePositionIntent`, not `runLeveragePositionOperation`; `notifySolver` is given `dstChainTxHash`; exits are sized from `getPositionCollateralBalance` and charge the fee from `getPositionInfo`.
46
70
 
47
71
  ## Related granular skills (same family)
48
72
 
@@ -1,12 +1,12 @@
1
1
  ---
2
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.'
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 (`/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
4
  ---
5
5
 
6
6
  # Leverage Yield API (Core SDK granular skill)
7
7
 
8
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`;
9
+ the backend **Leverage Yield API** (`/leverage-yield/*`). `sodax.api` is an alias for `sodax.backendApi`;
10
10
  `.leverageYield` is the leverage-yield client. 33 endpoints, one method each; every method returns
11
11
  `Promise<Result<T>>` (never throws) and validates the response. Errors carry `feature: 'backend'`,
12
12
  `context.api: 'leverageYield'`, `context.endpoint`.
@@ -23,6 +23,7 @@ Swap has materially different code paths depending on the answers. Don't skip:
23
23
  - Unsigned → `raw: true`, you handle relay yourself.
24
24
  3. **One-shot `swap()` or step-by-step (`createIntent` → backend submit → `postExecution`)?**
25
25
  - One-shot is the default for frontends. Step-by-step is for backends that already have a relay/orchestration layer.
26
+ - Step-by-step code must reproduce BOTH paths `swap()` runs internally — the backend submit-tx attempt *and* the client-side relay fallback on any non-success. The helpers behind `swap()` are package-internal, so the loop is hand-written: [`../integration/knowledge/recipes/manual-submit-tx-with-fallback.md`](../integration/knowledge/recipes/manual-submit-tx-with-fallback.md).
26
27
  4. **Market order or limit order?** Limit orders use a different params shape — `deadline` becomes optional (forced to `0n` internally), not required.
27
28
 
28
29
  ## Integration workflow (writing new v2 swap code)
@@ -63,7 +64,7 @@ Read in order. Skipping `ai-rules.md` is the most common cause of agents reverti
63
64
  - [`../partner/SKILL.md`](../partner/SKILL.md) — partner fees on swap.
64
65
  - [`../recovery/SKILL.md`](../recovery/SKILL.md) — stuck-asset recovery for failed swaps.
65
66
  - [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — `sodax.api.swaps.submitTx` and intent / orderbook lookups (step-by-step swap flow + diagnostics).
66
- - [`../swaps-api/SKILL.md`](../swaps-api/SKILL.md) — the typed Swaps API v2 backend client (`sodax.api.swaps`: quote, create-intent, submit-tx, fees) the swap flow calls under the hood.
67
+ - [`../swaps-api/SKILL.md`](../swaps-api/SKILL.md) — the typed Swaps API backend client (`sodax.api.swaps`: quote, create-intent, submit-tx, fees) the swap flow calls under the hood.
67
68
 
68
69
  For tasks spanning multiple features, load the broad [`sodax-sdk` skill](../SKILL.md) instead.
69
70
 
@@ -1,12 +1,12 @@
1
1
  ---
2
2
  name: sodax-sdk-swaps-api
3
- description: 'Granular skill for the @sodax/sdk v2 Swaps API client — `sodax.api.swaps` (class SwapsApiService), a typed HTTP client for the backend Swaps API v2 (`/swaps/*`, 21 endpoints: quote, deadline, allowance/approve, create-intent, intent submit/status/cancel/hash/packet/extra-data, limit orders, 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 swaps backend directly (e.g. "get a swap quote from the Sodax backend", "sodax.api.swaps", "submit swap tx", "createIntent via the backend API", "poll submit-tx status", "swaps API v2", "point swaps at a custom endpoint"). For the higher-level end-to-end swap orchestrator use the `swap` skill instead. Skill links into the parent sodax-sdk knowledge tree.'
3
+ description: 'Granular skill for the @sodax/sdk v2 Swaps API client — `sodax.api.swaps` (class SwapsApiService), a typed HTTP client for the backend Swaps API (`/swaps/*`, 21 endpoints: quote, deadline, allowance/approve, create-intent, intent submit/status/cancel/hash/packet/extra-data, limit orders, 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 swaps backend directly (e.g. "get a swap quote from the Sodax backend", "sodax.api.swaps", "submit swap tx", "createIntent via the backend API", "poll submit-tx status", "swaps API v2", "point swaps at a custom endpoint"). For the higher-level end-to-end swap orchestrator use the `swap` skill instead. Skill links into the parent sodax-sdk knowledge tree.'
4
4
  ---
5
5
 
6
6
  # Swaps API (Core SDK granular skill)
7
7
 
8
8
  Granular skill for `sodax.api.swaps` (class `SwapsApiService`) — the typed HTTP client for the backend
9
- **Swaps API v2** (`/swaps/*`). `sodax.api` is an alias for `sodax.backendApi`; `.swaps` is the swaps
9
+ **Swaps API** (`/swaps/*`). `sodax.api` is an alias for `sodax.backendApi`; `.swaps` is the swaps
10
10
  client. 21 endpoints, one method each; every method returns `Promise<Result<T>>` (never throws) and
11
11
  validates the response. Errors carry `feature: 'backend'`, `context.api: 'swaps'`, `context.endpoint`.
12
12
 
@@ -8,7 +8,7 @@ Backed by [viem](https://viem.sh). One class covers **every** SODAX EVM spoke ch
8
8
  | Interface | `IEvmWalletProvider` (from `@sodax/types`) |
9
9
  | Discriminant style | **Field presence** (no `type` field) |
10
10
  | Underlying SDK | `viem` |
11
- | Supported chains | Sonic (hub), Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera |
11
+ | Supported chains | Sonic (hub), Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera, Robinhood |
12
12
 
13
13
  ---
14
14
 
@@ -58,9 +58,9 @@ Bitcoin's signing flow inspects the connected address and picks the right method
58
58
  | P2SH (legacy multi-sig, `3…`) | ECDSA | Unisat, Xverse, OKX, Hana |
59
59
  | P2PKH (legacy, `1…`) | ECDSA | Unisat, Xverse, OKX, Hana |
60
60
 
61
- If a custom connector implements only one of the two methods, calling `signMessage` from a wrongly-typed address surfaces the error inline.
61
+ The methods live on the connector's `IBitcoinWalletProvider`, not on the connector: `chainRegistry` resolves the provider via `getWalletProvider()` (falling back to `recreateWalletProvider(xAccount)` after a page reload) and dispatches on it. A custom connector must return a provider implementing both methods; if it implements only one, calling `signMessage` from a wrongly-typed address surfaces the error inline.
62
62
 
63
- The same logic mirrors the SDK's `BitcoinSpokeProvider.authenticateWithWallet` — the React layer doesn't reinvent the dispatch.
63
+ The same logic mirrors the SDK's `RadfiProvider.authenticateWithWallet` — the React layer doesn't reinvent the dispatch.
64
64
 
65
65
  ---
66
66