@sodax/skills 2.1.0-rc.2 → 2.1.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.
Files changed (28) hide show
  1. package/README.md +1 -1
  2. package/package.json +1 -1
  3. package/skills/sodax-dapp-kit/integration/knowledge/architecture.md +31 -0
  4. package/skills/sodax-dapp-kit/integration/knowledge/features/bridge.md +5 -0
  5. package/skills/sodax-dapp-kit/integration/knowledge/features/dex.md +5 -0
  6. package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +9 -2
  7. package/skills/sodax-dapp-kit/integration/knowledge/features/migration.md +5 -0
  8. package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +5 -0
  9. package/skills/sodax-dapp-kit/integration/knowledge/features/staking.md +5 -0
  10. package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +5 -0
  11. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +6 -4
  12. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +2 -1
  13. package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +2 -0
  14. package/skills/sodax-sdk/bridge-api/SKILL.md +5 -5
  15. package/skills/sodax-sdk/integration/knowledge/architecture.md +19 -0
  16. package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +5 -0
  17. package/skills/sodax-sdk/integration/knowledge/features/bridge-api.md +5 -5
  18. package/skills/sodax-sdk/integration/knowledge/features/bridge.md +8 -2
  19. package/skills/sodax-sdk/integration/knowledge/features/dex.md +6 -0
  20. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +17 -3
  21. package/skills/sodax-sdk/integration/knowledge/features/migration.md +6 -0
  22. package/skills/sodax-sdk/integration/knowledge/features/money-market.md +6 -0
  23. package/skills/sodax-sdk/integration/knowledge/features/staking.md +6 -0
  24. package/skills/sodax-sdk/integration/knowledge/features/swap.md +7 -1
  25. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +23 -0
  26. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +1 -1
  27. package/skills/sodax-sdk/leverage-yield/SKILL.md +3 -1
  28. package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
package/README.md CHANGED
@@ -49,4 +49,4 @@ LLM training data drifts: snippets from chat often use stale method names, resha
49
49
 
50
50
  ## Feedback
51
51
 
52
- If your agent generates wrong code despite reading the docs, that's a doc bug — please open an issue on the [Sodax SDKs repo](https://github.com/icon-project/sodax-sdks/issues) with the prompt and the incorrect output. The per-skill `knowledge/` subtrees are structurally CI-guarded (frontmatter, link resolution); prose claims benefit from real-world feedback.
52
+ If your agent generates wrong code despite reading the docs, that's a doc bug — please open an issue on the [SODAX SDKs repo](https://github.com/icon-project/sodax-sdks/issues) with the prompt and the incorrect output. The per-skill `knowledge/` subtrees are structurally CI-guarded (frontmatter, link resolution); prose claims benefit from real-world feedback.
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "2.1.0-rc.2",
7
+ "version": "2.1.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": [
@@ -198,6 +198,37 @@ After translating, the public hook signature is `SafeUseMutationResult<T, Error,
198
198
 
199
199
  The dual API means consumers never have to choose between React Query's error model and `Result<T>` ergonomics — both are exposed by the same hook.
200
200
 
201
+ ## Approve hooks can prompt the wallet twice
202
+
203
+ Every `use*Approve` hook is unchanged and still resolves to a single transaction hash. But a few
204
+ ERC-20s of the 2017 TetherToken lineage — Ethereum USDT is the only one in the SODAX token list today
205
+ — reject an allowance change from one non-zero value to another. When the connected wallet already
206
+ holds a stale allowance on such a token, the SDK sends `approve(0)` first, waits for it to be mined,
207
+ and only then sends the real approval. The user therefore signs **twice**, and the hash the hook
208
+ resolves with is the **last** transaction's.
209
+
210
+ Nothing about the hook contract changes and there is no flag to set. What matters for UI:
211
+
212
+ - An `isPending` that renders a single "Approving…" now spans two wallet prompts. Say so in the copy,
213
+ or the second prompt reads as a bug.
214
+ - Anything estimating gas or counting transactions from "one approve = one transaction" is wrong on
215
+ that branch.
216
+ - If the second signature is rejected after the reset landed, the allowance is now zero, so the next
217
+ attempt is a single transaction — retrying is always safe.
218
+
219
+ On the unsigned (swaps-API) path, prefer **`useSwapsApiApproveAndBroadcast`**: it asks the API for
220
+ the transactions, then signs, broadcasts, and waits for each, resolving with
221
+ `{ approveTxHash, resetTxHash? }` only once the final approval has landed. A transaction that mines
222
+ but reverts rejects the mutation naming that step, so the approve is never sent over a reset that
223
+ did not take. It also invalidates `['swapsApi','allowance']` itself, because confirmation now
224
+ happens inside the hook.
225
+
226
+ `useSwapsApiApprove` still exists and returns the API's `{ tx, resetTx? }` verbatim — use it only
227
+ when you need to own signing. If you do, broadcast `resetTx` **first and wait for it to succeed**;
228
+ the approve is not a valid state transition until the reset has landed, so sending both together
229
+ spends the user's gas on a certain revert. Waiting is not enough on its own — check the receipt's
230
+ status, because a mined-and-reverted reset leaves the allowance exactly where it was.
231
+
201
232
  ## queryKey / mutationKey conventions (mandatory)
202
233
 
203
234
  Every `queryKey` and `mutationKey` follows the same structural rule. Enforced by `_mutationContract.test.ts` for mutation keys; reviewer-enforced for query keys.
@@ -19,6 +19,11 @@ useGetBridgeableAmount({ params: { from: XToken, to: XToken }, queryOptions });
19
19
  useGetBridgeableTokens({ params: { from: SpokeChainKey, to: SpokeChainKey, token: string }, queryOptions });
20
20
  ```
21
21
 
22
+ `use*Approve` is unchanged and still resolves to one transaction hash, but the SDK may send **two**
23
+ transactions on a token that rejects a non-zero to non-zero allowance change (Ethereum USDT today) —
24
+ the user signs twice and the hash is the **last** one's. An `isPending`-driven "Approving…" should say
25
+ so. See "Approve hooks can prompt the wallet twice" in [`architecture.md`](../architecture.md).
26
+
22
27
  ## Mutation params
23
28
 
24
29
  ```ts
@@ -35,6 +35,11 @@ useCreateSupplyLiquidityParams({ poolData, poolKey, minPrice, maxPrice, liquidit
35
35
  useCreateDecreaseLiquidityParams({ /* see source for fields */ });
36
36
  ```
37
37
 
38
+ `use*Approve` is unchanged and still resolves to one transaction hash, but the SDK may send **two**
39
+ transactions on a token that rejects a non-zero to non-zero allowance change (Ethereum USDT today) —
40
+ the user signs twice and the hash is the **last** one's. An `isPending`-driven "Approving…" should say
41
+ so. See "Approve hooks can prompt the wallet twice" in [`architecture.md`](../architecture.md).
42
+
38
43
  ## SDK param types (passed via `mutate({ params, walletProvider })`)
39
44
 
40
45
  Each dex mutation hook's TVars is `{ params: <SDKParamsType>, walletProvider, timeout? }`. The SDK param types below are what goes INSIDE `params` — they are not the TVars themselves.
@@ -13,6 +13,7 @@ useLeverageYieldVaultSwap({ mutationOptions }); // EXECUTE the built payload en
13
13
  useLeverageYieldNotifySolver({ mutationOptions }); // manual-flow: notify the solver after a self-driven relay
14
14
 
15
15
  // Reads
16
+ useLeverageYieldQuote({ params, queryOptions }); // vault deposit/withdraw quote (3s) — NOT useQuote
16
17
  useLeverageYieldEffectiveApr({ params, queryOptions }); // AAVE + LSD effective net APR (60s)
17
18
  useLeverageYieldPosition({ params, queryOptions }); // collateral/debt/ltv/healthFactor/idle (30s)
18
19
  useLeverageYieldTotalAssets({ params, queryOptions }); // vault TVL, 18-dp bigint (60s)
@@ -22,6 +23,11 @@ useLeverageYieldShareBalances({ params, queryOptions }); // per-chain share bala
22
23
 
23
24
  `deposit` / `withdraw` are **builders** — they assemble a `LeverageYieldSwapPayload`, they do NOT broadcast. Spread the built payload into `useLeverageYieldVaultSwap`'s `mutate`, adding the `walletProvider`. There is no dedicated leverage-yield approve hook: the swap-style deposit approves the spoke-side asset manager, so reuse `useSwapApprove` / `useSwapAllowance` (see Approval pattern).
24
25
 
26
+ `use*Approve` is unchanged and still resolves to one transaction hash, but the SDK may send **two**
27
+ transactions on a token that rejects a non-zero to non-zero allowance change (Ethereum USDT today) —
28
+ the user signs twice and the hash is the **last** one's. An `isPending`-driven "Approving…" should say
29
+ so. See "Approve hooks can prompt the wallet twice" in [`architecture.md`](../architecture.md).
30
+
25
31
  ## Mutation TVars
26
32
 
27
33
  ```ts
@@ -83,10 +89,11 @@ Leverage-yield has **no dedicated approve hook**. A deposit is a swap-style inte
83
89
 
84
90
  ## Return shapes
85
91
 
86
- All read hooks here are **already unwrapped** — they throw on SDK `!ok` so `isError` / `error` / `retry` engage. Read `data` directly; do NOT branch on `data.ok`.
92
+ Read hooks here are **already unwrapped** — they throw on SDK `!ok` so `isError` / `error` / `retry` engage. Read `data` directly; do NOT branch on `data.ok`. **`useLeverageYieldQuote` is the one exception**: it returns the SDK `Result` as `data`, matching `useQuote` on the swap side, because a quote failure ("no path", thin liquidity) is an expected UI branch and the `Result` preserves the solver's `detail.code`. Branch on `data?.ok` for that one hook only.
87
93
 
88
94
  | Hook | Returns |
89
95
  |---|---|
96
+ | `useLeverageYieldQuote` | `UseQueryResult<Result<SolverIntentQuoteResponse, SolverErrorResponse \| LeverageYieldLookupError> \| undefined, Error>` (Result **not** unwrapped; `undefined` while `payload` is undefined). Guard the error with `isSodaxError` — the `SolverErrorResponse` arm has `detail.code`, the `SodaxError` arm has `.code` (`VALIDATION_FAILED` / `LOOKUP_FAILED` / `UNKNOWN`) |
90
97
  | `useLeverageYieldDeposit` / `useLeverageYieldWithdraw` | `SafeUseMutationResult<LeverageYieldSwapPayload, Error, …>` (builder — `data` is the payload to spread into `useLeverageYieldVaultSwap`) |
91
98
  | `useLeverageYieldVaultSwap` | `SafeUseMutationResult<VaultSwapResponse, Error, …>` (`{ solverExecutionResponse, intent, intentDeliveryInfo }`) |
92
99
  | `useLeverageYieldNotifySolver` | `SafeUseMutationResult<SolverExecutionResponse, Error, …>` (`{ answer: 'OK', intent_hash }`) |
@@ -102,7 +109,7 @@ All read hooks here are **already unwrapped** — they throw on SDK `!ok` so `is
102
109
  2. **`useLeverageYieldShareBalances` returns an ARRAY, not a single query.** It fans out one `useQueries` row per holder. Aggregate yourself: `balances.reduce((acc, q) => acc + (q.data?.shares ?? 0n), 0n)`. `queryOptions` is spread into every per-holder query (no top-level options slot on `useQueries`).
103
110
  3. **The share-balance key segment is singular: `shareBalance`** (`['leverageYield', 'shareBalance', vault, chainKey, address]`) — one per holder, even though the hook name is plural.
104
111
  4. **Withdraw needs no spoke approval.** Don't gate it on `useSwapAllowance` — the hub-wallet `sendMessage` path approves the share spend internally. Only `deposit` needs the swap-domain allowance/approve pair.
105
- 5. **Deposit's per-intent `partnerFee` must be reflected in the quote.** If you charge a deposit-only fee (e.g. 1%), `vaultSwap`'s underlying `createVaultIntent` deducts it from `inputAmount` before the swap — quote on the post-fee amount, or `minOutputAmount` becomes unfillable and the intent never settles.
112
+ 5. **Quote vault flows with `useLeverageYieldQuote`, never `useQuote`.** `useQuote` deducts the effective *swap* fee (`swaps.partnerFee ?? fee`) while a vault intent charges the effective *leverage-yield* fee (`leverageYield.partnerFee ?? fee`) — they disagree whenever the two feature fees differ, and when the leverage-yield one is larger the `minOutputAmount` you derive is unfillable and the intent never settles. Pass the same per-intent `partnerFee` to `useLeverageYieldQuote` and to `useLeverageYieldDeposit` / `useLeverageYieldVaultSwap`, or omit it on both — either way the two sides resolve the same fee.
106
113
  6. **`useLeverageYieldVaultSwap` invalidates xBalances on both chains** (`['shared', 'xBalances', srcChainKey]` and `dstChainKey`) on success. Compose your own `onSuccess` after the hook's — it runs first.
107
114
  7. **`useLeverageYieldNotifySolver` is for the manual flow only.** `useLeverageYieldVaultSwap` already notifies the solver internally — only reach for the standalone notify hook when you built the intent with `sodax.leverageYield.createVaultIntent` and relayed it yourself. It does NOT invalidate any queries: its only var is `{ intent_tx_hash }` (no chain context), and the fill lands asynchronously afterward.
108
115
 
@@ -20,6 +20,11 @@ useMigrationApprove({ mutationOptions });
20
20
  useMigrationAllowance({ params: { params: <inner>, action: 'migrate' | 'revert' }, queryOptions });
21
21
  ```
22
22
 
23
+ `use*Approve` is unchanged and still resolves to one transaction hash, but the SDK may send **two**
24
+ transactions on a token that rejects a non-zero to non-zero allowance change (Ethereum USDT today) —
25
+ the user signs twice and the hash is the **last** one's. An `isPending`-driven "Approving…" should say
26
+ so. See "Approve hooks can prompt the wallet twice" in [`architecture.md`](../architecture.md).
27
+
23
28
  ## Mutation params
24
29
 
25
30
  ```ts
@@ -66,6 +66,11 @@ type UseATokensBalancesParams = ReadHookParams<Map<Address, bigint>, {
66
66
 
67
67
  > **Bitcoin `userAddress`**: always pass the **personal** address (the user's wallet address), not the Bound Exchange trading address. The read hooks (`useATokensBalances`, `useUserReservesData`, `useUserFormattedSummary`, `useGetUserHubWalletAddress`) automatically resolve to the trading-wallet-derived hub wallet when a Bound Exchange session is active — this is a local lookup with no network call and no throw on an unauthenticated session. See [`features/bitcoin.md`](bitcoin.md) for Bound Exchange session setup.
68
68
 
69
+ `use*Approve` is unchanged and still resolves to one transaction hash, but the SDK may send **two**
70
+ transactions on a token that rejects a non-zero to non-zero allowance change (Ethereum USDT today) —
71
+ the user signs twice and the hash is the **last** one's. An `isPending`-driven "Approving…" should say
72
+ so. See "Approve hooks can prompt the wallet twice" in [`architecture.md`](../architecture.md).
73
+
69
74
  ## Mutation params
70
75
 
71
76
  All four user mutations share the same TVars shape (only the `action` literal differs):
@@ -35,6 +35,11 @@ useInstantUnstakeRatio({ params, queryOptions });
35
35
  useConvertedAssets({ params, queryOptions });
36
36
  ```
37
37
 
38
+ `use*Approve` is unchanged and still resolves to one transaction hash, but the SDK may send **two**
39
+ transactions on a token that rejects a non-zero to non-zero allowance change (Ethereum USDT today) —
40
+ the user signs twice and the hash is the **last** one's. An `isPending`-driven "Approving…" should say
41
+ so. See "Approve hooks can prompt the wallet twice" in [`architecture.md`](../architecture.md).
42
+
38
43
  ## Mutation TVars
39
44
 
40
45
  ```ts
@@ -24,6 +24,11 @@ useCancelLimitOrder({ mutationOptions }); // TVars are FLAT: { srcChai
24
24
 
25
25
  (In actual code, you import each hook directly: `import { useSwap, useSwapAllowance, ... } from '@sodax/dapp-kit'`.)
26
26
 
27
+ `use*Approve` is unchanged and still resolves to one transaction hash, but the SDK may send **two**
28
+ transactions on a token that rejects a non-zero to non-zero allowance change (Ethereum USDT today) —
29
+ the user signs twice and the hash is the **last** one's. An `isPending`-driven "Approving…" should say
30
+ so. See "Approve hooks can prompt the wallet twice" in [`architecture.md`](../architecture.md).
31
+
27
32
  ## Mutation params
28
33
 
29
34
  ```ts
@@ -19,6 +19,7 @@ Leveraged-yield ERC-4626 vaults on Sonic. Deposit any token → `lsoda*` shares,
19
19
 
20
20
  | Hook | Purpose |
21
21
  |------|---------|
22
+ | `useLeverageYieldQuote` | Quote a deposit/withdraw with the leverage-yield fee (returns the SDK `Result` as `data`) |
22
23
  | `useSwapAllowance` | Check spoke `inputToken` approval (deposit only — swap-domain hook) |
23
24
  | `useLeverageYieldEffectiveApr` | AAVE + LSD effective net APR |
24
25
  | `useLeverageYieldPosition` | Live position (collateral, debt, LTV, health factor, idle) |
@@ -107,7 +108,7 @@ function DepositForm({ vault, srcAddress, inputToken }: { vault: Address; srcAdd
107
108
  const built = await buildDeposit({
108
109
  vault, srcChainKey: chainKey, srcAddress, inputToken,
109
110
  inputAmount: parseUnits(amount, 18),
110
- minOutputAmount: 0n, // quote via sodax.swaps.getQuote (token_dst = vault), then subtract slippage
111
+ minOutputAmount: 0n, // size via useLeverageYieldQuote (token_dst = vault), then subtract slippage
111
112
  partnerFee: DEPOSIT_PARTNER_FEE, // per-intent fee — must match the quote's post-fee amount
112
113
  });
113
114
  if (!built.ok) return;
@@ -149,7 +150,7 @@ function WithdrawButton({ vault, srcAddress, outputToken, shares }: { vault: Add
149
150
  vault, srcChainKey: chainKey, srcAddress,
150
151
  dstChainKey: chainKey, outputToken,
151
152
  inputAmount: shares, // lsoda* shares to burn
152
- minOutputAmount: 0n, // quote via sodax.swaps.getQuote (token_src = vault), then subtract slippage
153
+ minOutputAmount: 0n, // size via useLeverageYieldQuote (token_src = vault), then subtract slippage
153
154
  });
154
155
  if (!built.ok) return;
155
156
  await vaultSwap({ ...built.value, walletProvider }); // built.value.hubWalletSwap === true
@@ -162,7 +163,8 @@ function WithdrawButton({ vault, srcAddress, outputToken, shares }: { vault: Add
162
163
  ## Notes
163
164
 
164
165
  - **Two roles:** `deposit` / `withdraw` *build* a `LeverageYieldSwapPayload`; `useLeverageYieldVaultSwap` *executes* it. Always spread the built payload into the executor with a `walletProvider`.
165
- - **Quotes:** size `minOutputAmount` with `sodax.swaps.getQuote` — vault address as `token_dst` (deposit) or `token_src` (withdraw), since `lsoda*` shares are solver-tradeable. Subtract your slippage tolerance.
166
- - **Deposit fee:** a per-intent `partnerFee` is deducted from `inputAmount` before the swap; quote on the post-fee amount or the intent won't fill.
166
+ - **Quotes:** size `minOutputAmount` with `useLeverageYieldQuote` — vault address as `token_dst` (deposit) or `token_src` (withdraw). Not `useQuote`: that one deducts the effective *swap* fee, while the vault intent charges the effective *leverage-yield* fee, so the quote and the intent disagree whenever the two feature fees differ. It returns the SDK `Result` as `data` (branch on `data?.ok`), unlike the other leverage-yield read hooks. Subtract your slippage tolerance.
167
+ - **Fees apply BOTH ways.** Deposits *and* withdrawals are charged the effective leverage-yield fee (`leverageYield.partnerFee ?? fee`); both builders accept an optional `partnerFee` to override it per intent. The fee comes out of `inputAmount` before the swap, so pass the same `partnerFee` to `useLeverageYieldQuote` or the quote is sized on the wrong net input and the intent won't fill. On a withdraw the input token is the vault, so the fee is taken in **`lsoda*` shares** — the receiver accrues vault shares, not the output token.
168
+ - **Configured fee:** vault flows are monetized via `leverageYield.partnerFee` (else the global `fee`). `swaps.partnerFee` does not apply to them.
167
169
  - **Withdraw:** no spoke approval — the hub wallet authorises the share spend via `Connection.sendMessage`. Output lands at `recipient` (defaults to `srcAddress`) on `dstChainKey`.
168
170
  - **Reads** (`useLeverageYieldEffectiveApr`, `Position`, `TotalAssets`, `PreviewRedeem`) are already unwrapped — read `data` directly. `useLeverageYieldShareBalances` returns an array; aggregate the `shares` yourself.
@@ -197,7 +197,8 @@ Typed React Query wrappers over the backend Swaps API v2 (`sodax.api.swaps.*`),
197
197
 
198
198
  | Hook | Type |
199
199
  |---|---|
200
- | `useSwapsApiApprove` | Mutation; builds unsigned approval tx |
200
+ | `useSwapsApiApprove` | Mutation; builds unsigned approval tx(s) — `{ tx, resetTx? }`, caller signs |
201
+ | `useSwapsApiApproveAndBroadcast` | Mutation; builds **and** signs/broadcasts/waits — preferred; `{ approveTxHash, resetTxHash? }` |
201
202
  | `useSwapsApiCreateIntent` | Mutation; builds `{ tx, intent, relayData }` |
202
203
  | `useSwapsApiSubmitIntent` | Mutation; submits broadcast intent to the relay |
203
204
  | `useSwapsApiCancelIntent` | Mutation; builds unsigned cancel tx |
@@ -176,6 +176,7 @@ Typed wrappers over `sodax.api.swaps.*` (one per Swaps API v2 endpoint), all key
176
176
  | `['swapsApi', 'solverFee', amount]` | `useSwapsApiSolverFee` |
177
177
  | `['swapsApi', 'submitTx', 'status', txHash, srcChainKey]` | `useSwapsApiSubmitTxStatus` — both identifiers required |
178
178
  | `['swapsApi', 'approve']` | `useSwapsApiApprove` mutation |
179
+ | `['swapsApi', 'approveAndBroadcast']` | `useSwapsApiApproveAndBroadcast` mutation |
179
180
  | `['swapsApi', 'createIntent']` | `useSwapsApiCreateIntent` mutation |
180
181
  | `['swapsApi', 'submitIntent']` | `useSwapsApiSubmitIntent` mutation |
181
182
  | `['swapsApi', 'cancelIntent']` | `useSwapsApiCancelIntent` mutation |
@@ -203,6 +204,7 @@ Typed wrappers over `sodax.api.bridge.*` (one per Bridge API v2 endpoint), all k
203
204
 
204
205
  | Key | Hook |
205
206
  |---|---|
207
+ | `['leverageYield', 'quote', payload]` | `useLeverageYieldQuote` (payload object with `amount` and any `partnerFee.amount` stringified — React Query hashes keys with `JSON.stringify`, which throws on bigint) |
206
208
  | `['leverageYield', 'effectiveApr', vault]` | `useLeverageYieldEffectiveApr` |
207
209
  | `['leverageYield', 'position', vault]` | `useLeverageYieldPosition` |
208
210
  | `['leverageYield', 'totalAssets', vault]` | `useLeverageYieldTotalAssets` |
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sodax-sdk-bridge-api
3
- description: 'Granular skill for the @sodax/sdk v2 Bridge API client — `sodax.api.bridge` (class BridgeApiService), a typed HTTP client for the backend Bridge API v2 (`/bridge/*`: tokens, allowance/approve, create-bridge-intent, submit-tx + status, fee/bridgeable-amount/bridgeable discovery). Every method returns Promise<Result<T>>, never throws, and validates the response. Use when the task calls the bridge backend directly (e.g. "sodax.api.bridge", "createBridgeIntent via the backend API", "submit bridge tx", "poll bridge submit-tx status", "bridge API v2", "point bridge at a custom endpoint", "bridgeOptions.useBackendSubmitTx"). For the higher-level end-to-end bridge orchestrator use the `bridge` skill instead. Skill links into the parent sodax-sdk knowledge tree.'
3
+ description: 'Granular skill for the @sodax/sdk v2 Bridge API client — `sodax.api.bridge` (class BridgeApiService), a typed HTTP client for the backend Bridge API v2 (`/bridge/*`: tokens, allowance/approve, create-bridge-intent, submit-tx + status, fee/bridgeable-amount/bridgeable discovery). Every method returns Promise<Result<T>>, never throws, and validates the response. Use when the task calls the bridge backend directly (e.g. "sodax.api.bridge", "createBridgeIntent via the backend API", "submit bridge tx", "poll bridge submit-tx status", "bridge API v2", "point bridge at a custom endpoint", "bridge.useBackendSubmitTx"). For the higher-level end-to-end bridge orchestrator use the `bridge` skill instead. Skill links into the parent sodax-sdk knowledge tree.'
4
4
  ---
5
5
 
6
6
  # Bridge API (Core SDK granular skill)
@@ -25,7 +25,7 @@ validates the response. Errors carry `feature: 'backend'`, `context.api: 'bridge
25
25
  ## Integration workflow
26
26
 
27
27
  1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
28
- 2. [`../integration/knowledge/features/bridge-api.md`](../integration/knowledge/features/bridge-api.md) — the full client: signatures, deltas vs swaps (no intent, FULL relayData envelope, 5-state tolerant status), common call shapes (create-intent, submit-tx + status), the read-only fee/bridgeable-amount/bridgeable discovery quotes, per-call overrides, `bridgeOptions.useBackendSubmitTx`.
28
+ 2. [`../integration/knowledge/features/bridge-api.md`](../integration/knowledge/features/bridge-api.md) — the full client: signatures, deltas vs swaps (no intent, FULL relayData envelope, 5-state tolerant status), common call shapes (create-intent, submit-tx + status), the read-only fee/bridgeable-amount/bridgeable discovery quotes, per-call overrides, `bridge.useBackendSubmitTx`.
29
29
  3. For the end-to-end bridge flow that wraps these calls → [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md); for the sibling swaps client → [`../integration/knowledge/features/swaps-api.md`](../integration/knowledge/features/swaps-api.md); for the read client (`sodax.backendApi`) → [`../integration/knowledge/features/backend-api.md`](../integration/knowledge/features/backend-api.md).
30
30
  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).
31
31
 
@@ -42,10 +42,10 @@ validates the response. Errors carry `feature: 'backend'`, `context.api: 'bridge
42
42
  ## Migration workflow (on-chain → API)
43
43
 
44
44
  There is **no v1 Bridge API** — the typed `sodax.api.bridge` client is v2-new. The relevant move is from the
45
- on-chain `sodax.bridge.bridge()` orchestrator to the API client (or to the orchestrator's opt-in backend
46
- path via `bridgeOptions.useBackendSubmitTx`):
45
+ on-chain `sodax.bridge.bridge()` orchestrator to the API client (or to the orchestrator's default-on backend
46
+ path via `bridge.useBackendSubmitTx`):
47
47
 
48
- 1. [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md) — the on-chain `BridgeService` orchestrator and the `bridgeOptions.useBackendSubmitTx` toggle that routes its spoke-deposit through this API with a client-side fallback.
48
+ 1. [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md) — the on-chain `BridgeService` orchestrator and the `bridge.useBackendSubmitTx` toggle that routes its spoke-deposit through this API with a client-side fallback.
49
49
  2. For the v1 → v2 reshape of the on-chain bridge itself (chain-key routing, `Result<T>`, error unions) → [`../migration-v1-to-v2/knowledge/features/bridge.md`](../migration-v1-to-v2/knowledge/features/bridge.md).
50
50
 
51
51
  ## Verification
@@ -88,6 +88,25 @@ The chain key on the request payload (e.g. `srcChainKey: ChainKeys.ETHEREUM_MAIN
88
88
 
89
89
  The chain key is the bridge between the type system and runtime routing.
90
90
 
91
+ ### ERC-20 approval can take two transactions
92
+
93
+ A few ERC-20s of the 2017 TetherToken lineage reject an allowance change from one non-zero value to
94
+ another, so a wallet holding a stale allowance cannot approve at all until the allowance is zeroed.
95
+ Before a signed approval, `SpokeService` simulates the approve and, when it reverts, sends
96
+ `approve(0)` first, waits for it to be mined, then sends the real approval. The user signs twice.
97
+
98
+ Detection is behavioural — the simulated approve either reverts or it does not — never a token list,
99
+ so a token added or upgraded later is handled without a code change. Consumer impact:
100
+
101
+ - **Signed flows (`raw: false`)** are unchanged. Every feature `approve` still resolves to a single
102
+ transaction hash: the hash of the **last** transaction. Show step progress in the UI if you want,
103
+ but nothing breaks if you do not.
104
+ - **Unsigned flows (`raw: true`)** still return exactly one transaction from `approve`, which cannot
105
+ express a two-step plan. Use `sodax.swaps.buildApproveTxs({ params, raw: true })` instead — it
106
+ returns `{ approveTx, resetTx? }`. `resetTx` is present only for a guarded token holding a stale
107
+ allowance — broadcast it and wait for it to be mined first, because `approveTx` is not valid until
108
+ the reset has landed.
109
+
91
110
  ---
92
111
 
93
112
  ## 3. `Sodax` facade and service graph
@@ -59,6 +59,11 @@ if (!submitResult.ok) return;
59
59
 
60
60
  ## Swap-intent request DTO — `bound.accessToken` (Bitcoin TRADING)
61
61
 
62
+ `/swaps/approve` answers `ApproveResponseV2 = { tx, resetTx? }`. `resetTx` appears only when the
63
+ source token rejects a non-zero to non-zero allowance change (Ethereum USDT is the only listed one
64
+ today) **and** the wallet already holds a stale allowance — broadcast it first, wait for it to be
65
+ mined, then broadcast `tx`. Absent for every other token, so a client that ignores it keeps working.
66
+
62
67
  `CreateIntentParamsV2` is the shared wire-level request body behind the typed `/swaps/allowance/check`, `/swaps/approve`, and `/swaps/intents` calls (the `IBackendApiV2` methods the SDK drives internally). It inherits the swap extras — `partnerFee`, `srcPublicKey`, and `bound` — from `SwapExtrasV2`, the JSON-safe mirror of the SDK `SwapExtras` (`QuoteRequestV2` inherits the same trio for its `includeTxData=true` path). For Bitcoin **TRADING**-mode `raw` intents the Bound Exchange (Radfi) token is carried as `bound.accessToken` — passed in the request body instead of an `x-bound-access-token` header so it stays inside the typed DTO. Required only when the source chain is Bitcoin in TRADING mode; ignored otherwise.
63
68
 
64
69
  You rarely build this DTO yourself: `sodax.swaps.createIntent` takes the token via the chain-key-gated `extras.bound.accessToken` slot and maps it onto `CreateIntentParamsV2.bound.accessToken`. See [`swap.md`](swap.md) § `SwapExtras` and [`../chain-specifics.md`](../chain-specifics.md) § "Bitcoin PSBT and Bound Exchange" for the consumer-facing flow and token-injection points.
@@ -115,12 +115,12 @@ The Bridge API has no dedicated config slice — it always shares the base backe
115
115
  move the whole backend (including bridge) to a custom host, use the `CustomApiConfig` `baseApiConfig` slice
116
116
  (see [`backend-api.md`](backend-api.md) § "Custom backend").
117
117
 
118
- ## Orchestrator integration — `bridgeOptions.useBackendSubmitTx`
118
+ ## Orchestrator integration — `bridge.useBackendSubmitTx`
119
119
 
120
- `new Sodax({ bridgeOptions: { useBackendSubmitTx: true } })` opts the end-to-end `sodax.bridge.bridge()`
121
- into routing the spoke-deposit through this API (`submit-tx` + status poll) with an automatic fall back to
122
- the client-side relay on any non-success. **Default OFF.** This is a distinct key from
123
- `swapsOptions.useBackendSubmitTx`. See [`bridge.md`](bridge.md) and the `CONFIGURE_SDK` doc.
120
+ `bridge.useBackendSubmitTx` (default `true`) routes the end-to-end `sodax.bridge.bridge()` through this
121
+ API (`submit-tx` + status poll) with an automatic fall back to the client-side relay on any non-success.
122
+ Set `new Sodax({ bridge: { useBackendSubmitTx: false } })` to force the client-side path. Independent of
123
+ `swaps.useBackendSubmitTx`. See [`bridge.md`](bridge.md) and the `CONFIGURE_SDK` doc.
124
124
 
125
125
  ## Error handling
126
126
 
@@ -33,7 +33,7 @@ type BridgeParams<K extends SpokeChainKey, Raw extends boolean> = {
33
33
  params: CreateBridgeIntentParams<K>;
34
34
  extras?: BridgeExtras<K>;
35
35
  skipSimulation?: boolean;
36
- timeout?: number; // shared budget for relay/poll; defaults to DEFAULT_RELAY_TX_TIMEOUT
36
+ timeout?: number; // per-attempt budget (backend attempt, then fallback relay); defaults to DEFAULT_RELAY_TX_TIMEOUT
37
37
  } & WalletProviderSlot<K, Raw>; // raw: true ⇒ no walletProvider; raw: false ⇒ required, chain-narrowed
38
38
 
39
39
  type CreateBridgeIntentParams<K extends SpokeChainKey> = {
@@ -83,7 +83,7 @@ const result = await sodax.bridge.bridge({
83
83
 
84
84
  ## Routing the spoke deposit through the backend
85
85
 
86
- `bridge()` relays client-side by default. `new Sodax({ bridgeOptions: { useBackendSubmitTx: true } })` opts into handing the broadcast deposit to the backend Bridge API instead (`sodax.api.bridge`), which relays server-side and falls back to the client-side relay on any non-success — safe because re-relaying is idempotent. Default is OFF. See [`bridge-api.md`](bridge-api.md).
86
+ `bridge()` routes the spoke-deposit through the backend Bridge API by default (`bridge.useBackendSubmitTx`, default ON) — `sodax.api.bridge` relays server-side and falls back to the client-side relay on any non-success — safe because re-relaying is idempotent. Set `new Sodax({ bridge: { useBackendSubmitTx: false } })` to force the client-side path. As with swaps, the SDK does not verify the deposit on-chain before handing it over — the backend verifies itself, so `verifyTxHash` runs on the client-side path only. `timeout` (defaults to `DEFAULT_RELAY_TX_TIMEOUT`) is a PER-ATTEMPT budget, same terms as swaps: the backend attempt gets it and the fallback relay gets a fresh one starting after verification, so neither a stalled backend nor a slow confirmation shortens the fallback. Worst case is `createBridgeIntent + timeout + verification + max(timeout, RELAY_FALLBACK_FLOOR_MS)` — intent creation and verification (the source chain's `pollingConfig.maxTimeoutMs`) are not bounded by `timeout`. Bridge has no post-execution term. See [`bridge-api.md`](bridge-api.md).
87
87
 
88
88
  ## Common call shapes
89
89
 
@@ -199,6 +199,12 @@ if (result.ok) {
199
199
  | `getBridgeableAmount` | `BridgeLimit = { amount, decimals, type }` |
200
200
  | `getBridgeableTokens` | `XToken[]` |
201
201
 
202
+ `approve` can send **two** transactions on a token that rejects a non-zero to non-zero allowance
203
+ change (Ethereum USDT is the only listed one today): `approve(0)` is mined first, then the real
204
+ approval, so the user signs twice. The returned value is unchanged — one hash, the **last**
205
+ transaction's. Detection simulates the approval, so never gate on a token list. Full note: "ERC-20
206
+ approval can take two transactions" in [`architecture.md`](../architecture.md).
207
+
202
208
  ## Error codes
203
209
 
204
210
  `feature: 'bridge'`. Per-method narrow unions:
@@ -165,6 +165,12 @@ The underlying read does not consult the wallet provider; pass `raw: true` to sa
165
165
 
166
166
  > `getPools()` is **synchronous** in v2 (was `Promise<PoolKey[]>` in v1). v2 reads from cached config — no I/O. `await sodax.dex.clService.getPools()` works (TS allows `await` on non-promise) but `.then(...)` is a runtime error.
167
167
 
168
+ `approve` can send **two** transactions on a token that rejects a non-zero to non-zero allowance
169
+ change (Ethereum USDT is the only listed one today): `approve(0)` is mined first, then the real
170
+ approval, so the user signs twice. The returned value is unchanged — one hash, the **last**
171
+ transaction's. Detection simulates the approval, so never gate on a token list. Full note: "ERC-20
172
+ approval can take two transactions" in [`architecture.md`](../architecture.md).
173
+
168
174
  ## Error codes
169
175
 
170
176
  `feature: 'dex'`. Per-method narrow unions:
@@ -14,6 +14,11 @@ Access: `sodax.leverageYield`. Service class: `LeverageYieldService`. Feature ta
14
14
  ## Public methods
15
15
 
16
16
  ```ts
17
+ // Quote — solver quote sized with the effective leverage-yield fee (NOT sodax.swaps.getQuote)
18
+ sodax.leverageYield.getQuote(payload: LeverageYieldQuoteParams): Promise<Result<SolverIntentQuoteResponse, SolverErrorResponse | LeverageYieldLookupError>>;
19
+ // token_dst = vault to quote a deposit, token_src = vault to quote a withdraw
20
+ // pass the same partnerFee here and to deposit()/withdraw()/vaultSwap(), or omit on all — never mix
21
+
17
22
  // Builders — assemble a LeverageYieldSwapPayload (spread into vaultSwap). Do NOT broadcast.
18
23
  sodax.leverageYield.deposit(params: LeverageYieldSwapDepositParams): Promise<Result<LeverageYieldSwapPayload, SodaxError>>;
19
24
  sodax.leverageYield.withdraw(params: LeverageYieldSwapWithdrawParams): Promise<Result<LeverageYieldSwapPayload, SodaxError>>;
@@ -76,13 +81,14 @@ type LeverageYieldSwapWithdrawParams = {
76
81
  recipient?: string; // defaults to srcAddress
77
82
  deadline?: bigint;
78
83
  solver?: Address;
84
+ partnerFee?: PartnerFee; // per-intent override; deducted from inputAmount, i.e. in lsoda* shares
79
85
  };
80
86
 
81
87
  // The execute-mode wrapper (createVaultIntent / vaultSwap). The two vault execution modifiers
82
88
  // live HERE, never on the generic swap surface:
83
89
  type VaultSwapActionParams<K, Raw> = SpokeExecActionParams<K, Raw, CreateIntentParams<K>> & {
84
90
  hubWalletSwap?: boolean; // withdraw: inputToken is hub-wallet lsoda*, authorise via Connection.sendMessage
85
- partnerFee?: PartnerFee; // beats config.swaps.partnerFee for this intent only
91
+ partnerFee?: PartnerFee; // beats config.leverageYield.partnerFee for this intent only
86
92
  };
87
93
  ```
88
94
 
@@ -97,7 +103,7 @@ const built = await sodax.leverageYield.deposit({
97
103
  srcAddress: '0x…',
98
104
  inputToken: '0x…weETHonArbitrum',
99
105
  inputAmount: parseUnits('1', 18),
100
- minOutputAmount: 0n, // quote via sodax.swaps.getQuote (token_dst = vault), then apply slippage
106
+ minOutputAmount: 0n, // quote via sodax.leverageYield.getQuote (token_dst = vault), then apply slippage
101
107
  partnerFee: { address: '0x…', percentage: 100 }, // optional 1% per-intent fee
102
108
  });
103
109
  if (!built.ok) return;
@@ -117,7 +123,7 @@ const built = await sodax.leverageYield.withdraw({
117
123
  dstChainKey: ChainKeys.ARBITRUM_MAINNET, // token delivered here
118
124
  outputToken: '0x…weETHonArbitrum',
119
125
  inputAmount: shareBalance, // lsoda* to burn
120
- minOutputAmount: 0n, // quote via sodax.swaps.getQuote (token_src = vault)
126
+ minOutputAmount: 0n, // quote via sodax.leverageYield.getQuote (token_src = vault)
121
127
  });
122
128
  if (!built.ok) return;
123
129
  // built.value.hubWalletSwap === true — no spoke approval; the hub wallet authorises the spend
@@ -138,6 +144,7 @@ await sodax.leverageYield.notifySolver({ intent_tx_hash: hubIntentTxHash });
138
144
 
139
145
  | Method | Success type |
140
146
  |---|---|
147
+ | `getQuote` | `SolverIntentQuoteResponse` (`{ quoted_amount }`) — error is `SolverErrorResponse \| LeverageYieldLookupError`, so discriminate with `isSodaxError(error)` before reading `.code` |
141
148
  | `deposit`, `withdraw` | `LeverageYieldSwapPayload` (`{ params: CreateIntentParams; hubWalletSwap?: true; partnerFee? }`) |
142
149
  | `createVaultIntent` | `CreateVaultIntentResult<K, Raw>` (`{ tx, intent & feeAmount, relayData }`) |
143
150
  | `vaultSwap` | `VaultSwapResponse` (`{ solverExecutionResponse, intent, intentDeliveryInfo }`) |
@@ -152,12 +159,19 @@ await sodax.leverageYield.notifySolver({ intent_tx_hash: hubIntentTxHash });
152
159
  | `getAsset` | `Address` |
153
160
  | `listVaults` / `getVault` / `getVaultByAddress` | `LeverageYieldVault[]` / `LeverageYieldVault \| undefined` (synchronous) |
154
161
 
162
+ `approve` can send **two** transactions on a token that rejects a non-zero to non-zero allowance
163
+ change (Ethereum USDT is the only listed one today): `approve(0)` is mined first, then the real
164
+ approval, so the user signs twice. The returned value is unchanged — one hash, the **last**
165
+ transaction's. Detection simulates the approval, so never gate on a token list. Full note: "ERC-20
166
+ approval can take two transactions" in [`architecture.md`](../architecture.md).
167
+
155
168
  ## Error codes
156
169
 
157
170
  `feature: 'leverageYield'`. Action discriminator on `context.action`: `'deposit' | 'withdraw' | 'approve' | 'allowanceCheck' | 'vaultSwap'`. Read methods partition on `context.method`.
158
171
 
159
172
  | Method | Narrow code union |
160
173
  |---|---|
174
+ | `getQuote` | `VALIDATION_FAILED` (non-positive `amount`, or a partner fee that leaves nothing to quote) `\| LOOKUP_FAILED` (unsupported token — solver payload could not be assembled) `\| UNKNOWN`, **or** a non-SodaxError `SolverErrorResponse` (`{ detail: { code, message } }`) straight from the solver. Guard with `isSodaxError(error)`. Context uses `tokenSrcChainKey` / `tokenDstChainKey`, not `srcChainKey` / `dstChainKey` — a withdraw quote's `token_src` is the hub, not the signing chain |
161
175
  | `deposit`, `withdraw` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| LOOKUP_FAILED \| UNKNOWN` (create-intent subset + `LOOKUP_FAILED` with `method: 'resolveDeadline'` when the default-deadline hub-block read fails) |
162
176
  | `createVaultIntent` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| UNKNOWN` (create-intent subset) |
163
177
  | `vaultSwap` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` |
@@ -205,6 +205,12 @@ try {
205
205
  | `getAvailableAmount` | `bigint` |
206
206
  | `BalnSwapService.claim` etc. | `TxReturnType<K, false>` (raw, not `Result`-wrapped) |
207
207
 
208
+ `approve` can send **two** transactions on a token that rejects a non-zero to non-zero allowance
209
+ change (Ethereum USDT is the only listed one today): `approve(0)` is mined first, then the real
210
+ approval, so the user signs twice. The returned value is unchanged — one hash, the **last**
211
+ transaction's. Detection simulates the approval, so never gate on a token list. Full note: "ERC-20
212
+ approval can take two transactions" in [`architecture.md`](../architecture.md).
213
+
208
214
  ## Error codes
209
215
 
210
216
  `feature: 'migration'`. Per-method narrow unions:
@@ -164,6 +164,12 @@ The `action` field routes to the right token under the hood — relevant for rep
164
164
 
165
165
  > Every cross-chain mutation across the SDK (bridge, staking, dex, migration, MM) returns `TxHashPair = { srcChainTxHash, dstChainTxHash }` — there is no array-form variant in v2.
166
166
 
167
+ `approve` can send **two** transactions on a token that rejects a non-zero to non-zero allowance
168
+ change (Ethereum USDT is the only listed one today): `approve(0)` is mined first, then the real
169
+ approval, so the user signs twice. The returned value is unchanged — one hash, the **last**
170
+ transaction's. Detection simulates the approval, so never gate on a token list. Full note: "ERC-20
171
+ approval can take two transactions" in [`architecture.md`](../architecture.md).
172
+
167
173
  ## Error codes
168
174
 
169
175
  `feature: 'moneyMarket'`. Per-method narrow unions:
@@ -151,6 +151,12 @@ const allowed = await sodax.staking.isAllowanceValid({
151
151
 
152
152
  > All 5 mutation methods return `TxHashPair = { srcChainTxHash, dstChainTxHash }` because the SDK relays spoke→hub internally. When the user is already on the hub, both fields hold the same hash.
153
153
 
154
+ `approve` can send **two** transactions on a token that rejects a non-zero to non-zero allowance
155
+ change (Ethereum USDT is the only listed one today): `approve(0)` is mined first, then the real
156
+ approval, so the user signs twice. The returned value is unchanged — one hash, the **last**
157
+ transaction's. Detection simulates the approval, so never gate on a token list. Full note: "ERC-20
158
+ approval can take two transactions" in [`architecture.md`](../architecture.md).
159
+
154
160
  ## Error codes
155
161
 
156
162
  `feature: 'staking'`. Per-method narrow unions:
@@ -13,7 +13,7 @@ Access: `sodax.swaps`. Service class: `SwapService`. Feature tag for errors: `'s
13
13
 
14
14
  Two execution paths:
15
15
 
16
- - **`swap`** — full flow in one call. Wraps `createIntent` + relay + `postExecution`. Returns `SwapResponse` on success. Opt into a **backend-driven 2-step** variant (the backend relays + post-executes server-side) with `new Sodax({ swapsOptions: { useBackendSubmitTx: true } })`; on any non-success it falls back to the client-side relay, returning the same `SwapResponse`.
16
+ - **`swap`** — full flow in one call. Wraps `createIntent` + relay + `postExecution`. Returns `SwapResponse` on success. By default uses a **backend-driven 2-step** variant (`swaps.useBackendSubmitTx`, default `true` — the backend relays + post-executes server-side); on any non-success it falls back to the client-side relay, returning the same `SwapResponse`. Set `new Sodax({ swaps: { useBackendSubmitTx: false } })` to force client-side only. The SDK does NOT verify the tx on-chain before handing it to the backend — the backend verifies itself, so `verifyTxHash` (and `TX_VERIFICATION_FAILED`) belong to the client-side path only. `timeout` (defaults to `DEFAULT_RELAY_TX_TIMEOUT`) is a PER-ATTEMPT budget, not end-to-end: the backend attempt (submit POST + status poll) gets it, and if that attempt does not complete the client-side relay wait gets a fresh one starting after verification — so neither a stalled backend nor a slow source-chain confirmation shortens the fallback, and raising `timeout` grows both. Each backend request is clamped to `min(budget left in the attempt, api.timeout)`; `api.timeout` is configurable (packaged default `DEFAULT_BACKEND_API_TIMEOUT`), and once the attempt's remainder drops below it a single stalled request can spend what is left — the clamp bounds a request by the attempt, it does not guarantee a retry. Worst case is `createIntent + timeout + verification + max(timeout, RELAY_FALLBACK_FLOOR_MS) + postExecution`; verification is bounded by the source chain's `pollingConfig.maxTimeoutMs` (varies widely — Stacks is several times Sui — read `chains.ts`, and it is a no-op on EVM), and intent creation and post-execution are not bounded by `timeout` at all.
17
17
  - **`createIntent` + backend submit** — break it apart for custom relay handling. `createIntent` returns `{ tx, intent, relayData }`; submit `relayData.payload` to the backend swap-tx endpoint via `sodax.api.swaps.submitTx`.
18
18
 
19
19
  ## Public methods
@@ -264,6 +264,12 @@ type RelayExtraData = {
264
264
  };
265
265
  ```
266
266
 
267
+ `approve` can send **two** transactions on a token that rejects a non-zero to non-zero allowance
268
+ change (Ethereum USDT is the only listed one today): `approve(0)` is mined first, then the real
269
+ approval, so the user signs twice. The returned value is unchanged — one hash, the **last**
270
+ transaction's. Detection simulates the approval, so never gate on a token list. Full note: "ERC-20
271
+ approval can take two transactions" in [`architecture.md`](../architecture.md).
272
+
267
273
  ## Error codes
268
274
 
269
275
  `feature: 'swap'`. Per-method narrow unions:
@@ -57,6 +57,29 @@ sodax.api.swaps.getSubmitTxStatus(query: SubmitTxStatusQueryV2, config?): Promis
57
57
  The optional trailing `config?: RequestOverrideConfig` (`{ baseURL?, timeout?, headers? }`) on every method
58
58
  applies per-call overrides that take precedence over the service config (see "Per-call overrides" below).
59
59
 
60
+ ## `approve` can return two transactions
61
+
62
+ `ApproveResponseV2` is `{ tx, resetTx? }`. `resetTx` appears only when the source token rejects an
63
+ allowance change from one non-zero value to another (the 2017 TetherToken lineage) **and** the wallet
64
+ already holds a stale allowance — a wallet in that state cannot approve at all until it is zeroed.
65
+
66
+ Broadcast `resetTx` first and wait for it to be mined, then broadcast `tx`. The two cannot be
67
+ batched: the approval is only valid once the reset has landed on-chain.
68
+
69
+ ```ts
70
+ const { tx, resetTx } = approveResponse;
71
+
72
+ if (resetTx) {
73
+ const resetHash = await sendTransaction(resetTx);
74
+ await waitForTransactionReceipt(resetHash);
75
+ }
76
+
77
+ await sendTransaction(tx);
78
+ ```
79
+
80
+ The field is optional and absent for every other token, so ignoring it keeps existing behaviour —
81
+ it just cannot rescue a wallet stuck on a guarded token.
82
+
60
83
  ## Wire shapes — `bigint` vs decimal strings
61
84
 
62
85
  Request bodies that carry an `intent` struct (`cancelIntent`, `getIntentHash`,
@@ -18,7 +18,7 @@ const result = sodax.config.isValidSpokeChainKey(ChainKeys.ARBITRUM_MAINNET);
18
18
  import { Sodax, ChainKeys, type SodaxOptions } from '@sodax/sdk';
19
19
 
20
20
  // `SodaxOptions` = `DeepPartial<SodaxDefaultConfig>` (the data override) plus the client-side options:
21
- // `logger`, the global `fee`, and `swapsOptions` (e.g. `{ useBackendSubmitTx: true }` — opt swap() into the backend 2-step flow).
21
+ // `logger`, the global `fee`, and per-feature options on `swaps` / `bridge` (e.g. `{ useBackendSubmitTx: false }` — opt out of the default-on backend 2-step flow).
22
22
  const config: SodaxOptions = {
23
23
  // Per-chain overrides — merged with packaged defaults at the field level.
24
24
  chains: {
@@ -33,7 +33,9 @@ Granular skill for `LeverageYieldService` — `sodax.leverageYield`. Feature tag
33
33
  - **Using `getApr` as the headline number.** For LSD-backed vaults the AAVE-only spread is often negative; `getEffectiveApr` folds in the LSD staking yield (the real source of return).
34
34
  - **Passing a spoke address to `getShareBalance` / `getMaxWithdraw`.** Those take a hub address. Use the `*ForUser(vault, srcChainKey, srcAddress)` variants to resolve the hub wallet first.
35
35
  - **Gating withdraw on `approve` / `isAllowanceValid`.** Those are Sonic-direct allowance helpers for the vault's underlying asset; the swap-style withdraw authorises the share spend via a hub-wallet `Connection.sendMessage` (`hubWalletSwap: true`).
36
- - **Quoting on the pre-fee amount.** A deposit's per-intent `partnerFee` is deducted from `inputAmount` before the swap — quote (via the swap solver, `token_dst` = vault) on the post-fee amount.
36
+ - **Quoting a vault flow through `sodax.swaps.getQuote`.** It deducts the effective *swap* fee, while the vault intent charges the effective *leverage-yield* fee (`leverageYield.partnerFee ?? fee`) — the two disagree whenever the feature fees differ. It can be made to agree by passing the leverage-yield fee explicitly (with a zero fee — `{ address, percentage: 0 }` — where that fee is `undefined`, since an explicit `undefined` falls back to the swap fee), but prefer `sodax.leverageYield.getQuote` (`token_dst` = vault for a deposit, `token_src` = vault for a withdraw).
37
+ - **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
+ - **Assuming `swaps.partnerFee` monetizes vault flows.** It does not — configure `leverageYield.partnerFee` (or the global `fee`).
37
39
 
38
40
  ## Verification
39
41
 
@@ -84,7 +84,7 @@ import { SuiWalletProvider } from '@sodax/wallet-sdk-core';
84
84
 
85
85
  // Private-key — DERIVED FROM MNEMONIC, not a raw key
86
86
  const suiPk = new SuiWalletProvider({
87
- rpcUrl: 'https://fullnode.mainnet.sui.io:443',
87
+ rpcUrl: 'https://sui-rpc.publicnode.com',
88
88
  mnemonics: 'word1 word2 … word12',
89
89
  });
90
90