@sodax/skills 2.0.0-rc.17 → 2.0.0-rc.19
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 +3 -3
- package/package.json +1 -1
- package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +3 -3
- package/skills/sodax-dapp-kit/bridge/SKILL.md +3 -3
- package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +22 -7
- package/skills/sodax-dapp-kit/integration/knowledge/features/dex.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +45 -3
- package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +32 -0
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +9 -7
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +1 -1
- package/skills/sodax-dapp-kit/money-market/SKILL.md +1 -1
- package/skills/sodax-dapp-kit/swap/SKILL.md +2 -2
- package/skills/sodax-sdk/SKILL.md +5 -4
- package/skills/sodax-sdk/backend-api/SKILL.md +17 -15
- package/skills/sodax-sdk/dex/SKILL.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/architecture.md +9 -8
- package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +21 -16
- package/skills/sodax-sdk/integration/knowledge/features/bridge.md +14 -14
- package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
- package/skills/sodax-sdk/integration/knowledge/features/migration.md +73 -28
- package/skills/sodax-sdk/integration/knowledge/features/money-market.md +18 -24
- package/skills/sodax-sdk/integration/knowledge/features/partner.md +27 -4
- package/skills/sodax-sdk/integration/knowledge/features/recovery.md +5 -4
- package/skills/sodax-sdk/integration/knowledge/features/staking.md +2 -2
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +23 -22
- package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +166 -0
- package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
- package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +2 -1
- package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +3 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
- package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +8 -2
- package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +12 -3
- package/skills/sodax-sdk/migration/SKILL.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +5 -5
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +23 -23
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/migration.md +29 -27
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +10 -5
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +7 -7
- package/skills/sodax-sdk/money-market/SKILL.md +3 -3
- package/skills/sodax-sdk/recovery/SKILL.md +1 -1
- package/skills/sodax-sdk/swap/SKILL.md +4 -3
- package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
- package/skills/sodax-wallet-sdk-core/SKILL.md +2 -2
- package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +1 -1
- package/skills/sodax-wallet-sdk-core/evm/SKILL.md +3 -3
- package/skills/sodax-wallet-sdk-core/icon/SKILL.md +4 -4
- package/skills/sodax-wallet-sdk-core/injective/SKILL.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
- package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +1 -1
- package/skills/sodax-wallet-sdk-react/connect/SKILL.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +2 -2
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +6 -6
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +2 -2
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +3 -3
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
- package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +1 -1
- package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +1 -1
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/backend-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/backend-api`, `sodax-sdk/swaps-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, backend-api) | `sodax-sdk/<feature>` (granular, covers both modes via internal links). Add `sodax-wallet-sdk-core` (integration) if it signs and lives outside React. Skip the broad `sodax-sdk` skill |
|
|
29
|
+
| **Scaffolding ONE specific Core SDK feature** (swap, money-market, bridge, staking, dex, leverage-yield, migration, partner, recovery, 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 |
|
|
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 |
|
|
@@ -63,7 +63,7 @@ packages/skills/
|
|
|
63
63
|
├── sodax-build/ {SKILL.md, knowledge/ (flat)} — cross-cutting front-door / ideation skill; no mode split, no granular children
|
|
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
|
-
│ leverage-yield, migration, partner, recovery, backend-api}
|
|
66
|
+
│ leverage-yield, migration, partner, recovery, backend-api, swaps-api}
|
|
67
67
|
├── sodax-wallet-sdk-core/ {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
|
|
68
68
|
│ <chain>/SKILL.md children — evm, solana, sui, bitcoin, stellar, icon,
|
|
69
69
|
│ injective, near, stacks}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-dapp-kit-auxiliary-services
|
|
3
|
-
description: 'Granular skill for the @sodax/dapp-kit v2 auxiliary surfaces — partner fee claiming (useFeeClaimSwap, useApproveToken, useSetSwapPreference, useGetAutoSwapPreferences, useIsTokenApproved), recovery (useHubAssetBalances, useWithdrawHubAsset), read-only backend queries (useBackendIntentByTxHash, useBackendUserIntents, useBackendOrderbook, useBackendMoneyMarketPosition,
|
|
3
|
+
description: 'Granular skill for the @sodax/dapp-kit v2 auxiliary surfaces — partner fee claiming (useFeeClaimSwap, useApproveToken, useSetSwapPreference, useGetAutoSwapPreferences, useIsTokenApproved), recovery (useHubAssetBalances, useWithdrawHubAsset), read-only backend queries (useBackendIntentByTxHash, useBackendUserIntents, useBackendOrderbook, useBackendMoneyMarketPosition), the Swaps API v2 client hooks (useSwapsApiQuote, useSwapsApiSubmitTx, useSwapsApiStatus), and shared utilities (useSodaxContext, useHubProvider, useXBalances, useDeriveUserWalletAddress, useEstimateGas, useStellarTrustlineCheck, useRequestTrustline). Use when a React dapp task is partner fees, recovering stuck hub assets, backend data reads (intent tracking / orderbook / MM data, no wallet), or cross-cutting utilities (token balances, gas estimation, Stellar trustlines). Covers BOTH integration and migration. Links into the parent sodax-dapp-kit knowledge tree.'
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
6
|
version: '0.0.1'
|
|
@@ -17,7 +17,7 @@ Granular skill for the smaller `@sodax/dapp-kit` v2 surfaces grouped together: *
|
|
|
17
17
|
2. **Which surface?**
|
|
18
18
|
- **Partner fees:** `useIsTokenApproved` → `useApproveToken` → `useSetSwapPreference` → `useFeeClaimSwap` (returns `IntentAutoSwapResult`, NOT `SwapResponse`); `useGetAutoSwapPreferences`, `useFetchAssetsBalances` for reads.
|
|
19
19
|
- **Recovery:** `useHubAssetBalances` (list stuck hub assets) → `useWithdrawHubAsset` (withdraw one back to a spoke). Follows a *known* failed cross-chain op — investigate the failure first.
|
|
20
|
-
- **Backend reads (no wallet):** intent tracking (`useBackendIntentByTxHash` polls 1s, `useBackendIntentByHash`, `useBackendUserIntents`), orderbook (`useBackendOrderbook` — `pagination` nests under `params`), MM data (`useBackendMoneyMarketPosition` etc.),
|
|
20
|
+
- **Backend reads (no wallet):** intent tracking (`useBackendIntentByTxHash` polls 1s, `useBackendIntentByHash`, `useBackendUserIntents`), orderbook (`useBackendOrderbook` — `pagination` nests under `params`), MM data (`useBackendMoneyMarketPosition` etc.), and the Swaps API v2 client (`useSwapsApi*` — e.g. `useSwapsApiSubmitTx`, `useSwapsApiSubmitTxStatus`, `useSwapsApiQuote`).
|
|
21
21
|
- **Shared utilities:** `useSodaxContext`, `useHubProvider`, `useXBalances` (needs `xService` from wallet-sdk-react), `useDeriveUserWalletAddress` / `useGetUserHubWalletAddress`, `useEstimateGas`, `useStellarTrustlineCheck` / `useRequestTrustline`.
|
|
22
22
|
|
|
23
23
|
## Integration workflow (new v2 code)
|
|
@@ -55,7 +55,7 @@ Granular skill for the smaller `@sodax/dapp-kit` v2 surfaces grouped together: *
|
|
|
55
55
|
|
|
56
56
|
## Related granular skills (same family)
|
|
57
57
|
|
|
58
|
-
- [`../swap/SKILL.md`](../swap/SKILL.md) — `
|
|
58
|
+
- [`../swap/SKILL.md`](../swap/SKILL.md) — `useSwapsApiSubmitTx` + intent tracking are the backend half of the step-by-step swap flow; partner fee-claim reuses the swap intent layer.
|
|
59
59
|
- [`../money-market/SKILL.md`](../money-market/SKILL.md) — backend MM reads complement the on-chain MM action hooks.
|
|
60
60
|
|
|
61
61
|
For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-dapp-kit-bridge
|
|
3
|
-
description: 'Granular skill for the @sodax/dapp-kit v2 bridge feature only — React Query hooks for cross-chain token transfer via the hub-and-spoke vault: useBridge, useBridgeApprove, useBridgeAllowance, useGetBridgeableAmount, useGetBridgeableTokens. Use when a React dapp task is specifically bridging (e.g. "useBridge with dapp-kit", "bridge tokens cross-chain in React", "check bridgeable amount hook", "list bridgeable destinations"). useBridge resolves to TxHashPair = { srcChainTxHash, dstChainTxHash }. Covers BOTH integration (new v2 hooks) and migration (port v1 bridge hooks — field renames srcChainId→srcChainKey, recipient
|
|
3
|
+
description: 'Granular skill for the @sodax/dapp-kit v2 bridge feature only — React Query hooks for cross-chain token transfer via the hub-and-spoke vault: useBridge, useBridgeApprove, useBridgeAllowance, useGetBridgeableAmount, useGetBridgeableTokens. Use when a React dapp task is specifically bridging (e.g. "useBridge with dapp-kit", "bridge tokens cross-chain in React", "check bridgeable amount hook", "list bridgeable destinations"). useBridge resolves to TxHashPair = { srcChainTxHash, dstChainTxHash }. Covers BOTH integration (new v2 hooks) and migration (port v1 bridge hooks — field renames srcChainId→srcChainKey / srcAsset→srcToken / dstAsset→dstToken, new required srcAddress, recipient unchanged, mutateAsyncSafe). Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
6
|
version: '0.0.1'
|
|
@@ -38,14 +38,14 @@ Granular skill for the bridge hooks of `@sodax/dapp-kit` v2. queryKey/mutationKe
|
|
|
38
38
|
|
|
39
39
|
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
|
|
40
40
|
2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
|
|
41
|
-
3. [`../migration-v1-to-v2/knowledge/features/bridge.md`](../migration-v1-to-v2/knowledge/features/bridge.md) — `useBridge` param renames (`srcChainId` → `srcChainKey`, `
|
|
41
|
+
3. [`../migration-v1-to-v2/knowledge/features/bridge.md`](../migration-v1-to-v2/knowledge/features/bridge.md) — `useBridge` param renames (`srcChainId` → `srcChainKey`, `dstChainId` → `dstChainKey`, `srcAsset` → `srcToken`, `dstAsset` → `dstToken`; new required `srcAddress`; `recipient` is UNCHANGED — NOT renamed to `dstAddress`); `useGetBridgeableAmount` shape change (bigint → `BridgeLimit`).
|
|
42
42
|
|
|
43
43
|
## Verification
|
|
44
44
|
|
|
45
45
|
1. `pnpm tsc --noEmit` clean.
|
|
46
46
|
2. `useBridge` consumers destructure `{ srcChainTxHash, dstChainTxHash }` (no array/string).
|
|
47
47
|
3. `useGetBridgeableAmount` consumers read `data.amount` (not a scalar).
|
|
48
|
-
4. No `useSpokeProvider`, no `srcChainId`/`
|
|
48
|
+
4. No `useSpokeProvider`, no `srcChainId`/`srcAsset`/`dstAsset` v1 field names (migration only); `recipient` stays `recipient` (do NOT rename to `dstAddress`).
|
|
49
49
|
|
|
50
50
|
## Related granular skills (same family)
|
|
51
51
|
|
|
@@ -64,22 +64,36 @@ useBackendMoneyMarketAssetBorrowers({ params, queryOptions });
|
|
|
64
64
|
useBackendAllMoneyMarketBorrowers({ params: { pagination: { offset, limit } }, queryOptions });
|
|
65
65
|
```
|
|
66
66
|
|
|
67
|
-
###
|
|
67
|
+
### Swaps API (`sodax.api.swaps`)
|
|
68
|
+
|
|
69
|
+
Typed React Query wrappers over the backend **Swaps API v2** — one `useSwapsApi*` hook per endpoint of `sodax.api.swaps.*` (21 total: tokens, quote, deadline, allowance, approve, create / submit / cancel intent, status, intent hash / packet / extra-data, intent lookups, limit orders, gas estimate, fees, submit-tx + status). They call the backend HTTP API and are distinct from the on-chain `swap/` hooks (`useQuote`/`useStatus`/`useSwap`/…), which drive `sodax.swaps` (the on-chain `SwapService`). Reads take `{ params, queryOptions }`; the six actions (`approve`, `createIntent`, `submitIntent`, `cancelIntent`, `createLimitOrder`, `submitTx`) are mutations taking `{ mutationOptions }`, with domain inputs flowing through `mutate(vars)`.
|
|
68
70
|
|
|
69
71
|
```ts
|
|
70
72
|
// @ai-snippets-skip
|
|
71
|
-
|
|
72
|
-
|
|
73
|
+
useSwapsApiQuote({ params: { body }, queryOptions }); // query → sodax.api.swaps.getQuote
|
|
74
|
+
useSwapsApiSubmitTx({ mutationOptions }); // mutation → sodax.api.swaps.submitTx
|
|
75
|
+
useSwapsApiSubmitTxStatus({ params, queryOptions }); // query → sodax.api.swaps.getSubmitTxStatus
|
|
73
76
|
```
|
|
74
77
|
|
|
75
|
-
`
|
|
78
|
+
`useSwapsApiSubmitTx` is a mutation hook — per-call config (e.g. backend base URL) flows through `mutate(vars)`. The `request` is a `SubmitTxRequestV2` (`{ txHash, srcChainKey, walletAddress, intent, relayData }`):
|
|
76
79
|
|
|
77
80
|
```ts
|
|
78
81
|
// @ai-snippets-skip
|
|
79
|
-
const { mutateAsync: submitSwapTx } =
|
|
80
|
-
|
|
82
|
+
const { mutateAsync: submitSwapTx } = useSwapsApiSubmitTx();
|
|
83
|
+
// request: SubmitTxRequestV2 — relayData is the string payload; intent carries bigint fields
|
|
84
|
+
await submitSwapTx({ request, apiConfig: { baseURL: 'https://...' } });
|
|
81
85
|
```
|
|
82
86
|
|
|
87
|
+
`useSwapsApiSubmitTxStatus` polls the processing status and returns `SubmitTxStatusResponseV2 | undefined`. Its query runs only when **both** `txHash` and `srcChainKey` are supplied — the v2 status endpoint requires the source chain key:
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
// @ai-snippets-skip
|
|
91
|
+
const { data: status } = useSwapsApiSubmitTxStatus({ params: { txHash, srcChainKey } });
|
|
92
|
+
// status?.data?.status: 'pending' | 'relaying' | 'relayed' | 'posting_execution' | 'executed' | 'failed'
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
> The full `useSwapsApi*` hook list (with polling + types) is in [hooks-index.md](../reference/hooks-index.md); key shapes in [querykey-conventions.md](../reference/querykey-conventions.md). For non-React callers, `sodax.api.swaps` is documented in the `sodax-sdk` skill (integration mode).
|
|
96
|
+
|
|
83
97
|
## Shared utilities
|
|
84
98
|
|
|
85
99
|
Cross-cutting hooks used by other features.
|
|
@@ -193,7 +207,8 @@ The underlying SDK methods (`isStorageRegistered` / `registerStorage` on the NEA
|
|
|
193
207
|
| Hook | Polling | Notes |
|
|
194
208
|
|---|---|---|
|
|
195
209
|
| `useBackendIntentByTxHash` | 1s | once a `txHash` is supplied (refetch is unconditional, not "while pending") |
|
|
196
|
-
| `
|
|
210
|
+
| `useSwapsApiSubmitTxStatus` | 1s | requires `txHash` + `srcChainKey`; stops on `executed` / `failed` |
|
|
211
|
+
| `useSwapsApiStatus` | 1s | solver intent status; stops on status `3` / `4` |
|
|
197
212
|
| `useBackendOrderbook` | none | `staleTime: 30s` — fresh-window, no background refetch |
|
|
198
213
|
| `useExpiredUtxos` (bitcoin) | 60s | refetchInterval |
|
|
199
214
|
| `useQuote` (swap) | 3s | refetchInterval |
|
|
@@ -29,8 +29,8 @@ useLiquidityAmounts({ params, queryOptions });
|
|
|
29
29
|
// Param builders (compute derived params client-side) — these take a FLAT props object,
|
|
30
30
|
// NOT a `{ params }` wrapper. They return memoized derived params that the consumer adds
|
|
31
31
|
// `srcChainKey` + `srcAddress` to at the mutation call site.
|
|
32
|
-
useCreateDepositParams({ tokenIndex, amount, poolData, poolSpokeAssets
|
|
33
|
-
useCreateWithdrawParams({ tokenIndex, amount, poolData, poolSpokeAssets, dst? });
|
|
32
|
+
useCreateDepositParams({ tokenIndex, amount, poolData, poolSpokeAssets }); // no dst — deposits always target the hub
|
|
33
|
+
useCreateWithdrawParams({ tokenIndex, amount, poolData, poolSpokeAssets, dst? }); // dst? — withdraw routes hub → spoke
|
|
34
34
|
useCreateSupplyLiquidityParams({ poolData, poolKey, minPrice, maxPrice, liquidityToken0Amount, liquidityToken1Amount, slippageTolerance, positionId?, isValidPosition? });
|
|
35
35
|
useCreateDecreaseLiquidityParams({ /* see source for fields */ });
|
|
36
36
|
```
|
|
@@ -137,7 +137,7 @@ if (!isApproved) await approve({ params: supplyParams, walletProvider });
|
|
|
137
137
|
|
|
138
138
|
## Gotchas
|
|
139
139
|
|
|
140
|
-
1. **Health factor < 1.0 is liquidation territory.**
|
|
140
|
+
1. **Health factor < 1.0 is liquidation territory.** `healthFactor` is a **string** — coerce before comparing (`summary.healthFactor < 1.05` is a TS type error). A user with **no debt** returns the sentinel `'-1'`, so guard against it or you'll warn on a safe position: `const hf = Number(summary.healthFactor); if (hf !== -1 && hf < 1.05) { /* warn */ }` (use whatever margin your UX needs).
|
|
141
141
|
2. **Cross-chain delivery via `dstChainKey`/`dstAddress`** — supported on all four actions (supply / withdraw / borrow / repay). Omit for same-chain operations; don't pass `dstChainKey === srcChainKey` (let the default kick in).
|
|
142
142
|
3. **`useMMAllowance` is `enabled: false` for borrow/withdraw** — `data` stays `undefined` (not `true`). Treat "no allowance result for borrow/withdraw" as "approval not required" — those actions never need ERC-20 approval.
|
|
143
143
|
4. **Position queries take `{ spokeChainKey, userAddress }`** (NOT `srcChainKey`/`srcAddress` — those are mutation-side names). The hub wallet derivation is automatic.
|
|
@@ -91,7 +91,7 @@ type UseStatusParams = ReadHookParams<
|
|
|
91
91
|
1. **`Intent.srcChain` and `Intent.dstChain` keep their v1 names.** Even though request-side params use `srcChainKey`/`dstChainKey`, the read-side `Intent` type didn't rename. Don't blanket-replace these names.
|
|
92
92
|
2. **Default `mutationKey` is `['swap']`.** Use `useIsMutating({ mutationKey: ['swap'] })` to get a global "any swap in flight" state. Override via `mutationOptions.mutationKey` if you want narrower scoping per-call.
|
|
93
93
|
3. **Quotes auto-refresh every 3s** — pause polling by setting `queryOptions.refetchInterval: false` if the quote is in a non-visible UI.
|
|
94
|
-
4. **Token list has duplicate addresses across chains.** `sodax.swaps.getSupportedSwapTokens()` returns `Record<SpokeChainKey, readonly XToken[]>`. Flattening it (e.g. `Object.values(...).flat()`) yields multiple tokens that share a contract address (same token deployed on different chains). When rendering a flat token list, use a composite key like `${token.address}-${token.
|
|
94
|
+
4. **Token list has duplicate addresses across chains.** `sodax.swaps.getSupportedSwapTokens()` returns `Record<SpokeChainKey, readonly XToken[]>`. Flattening it (e.g. `Object.values(...).flat()`) yields multiple tokens that share a contract address (same token deployed on different chains). When rendering a flat token list, use a composite key like `${token.address}-${token.chainKey}` — not `token.address` alone. (`XToken` carries `chainKey`; there is no `blockchain_id` field.)
|
|
95
95
|
|
|
96
96
|
## Cross-references
|
|
97
97
|
|
|
@@ -31,12 +31,14 @@ Read-only data hooks. No wallet connection required.
|
|
|
31
31
|
| `useBackendMoneyMarketAssetBorrowers` | Borrowers for an asset |
|
|
32
32
|
| `useBackendAllMoneyMarketBorrowers` | All borrowers |
|
|
33
33
|
|
|
34
|
-
###
|
|
34
|
+
### Swaps API (`sodax.api.swaps`)
|
|
35
35
|
|
|
36
36
|
| Hook | Purpose |
|
|
37
37
|
|------|---------|
|
|
38
|
-
| `
|
|
39
|
-
| `
|
|
38
|
+
| `useSwapsApiSubmitTx` | Submit swap tx to backend |
|
|
39
|
+
| `useSwapsApiSubmitTxStatus` | Check submitted swap status |
|
|
40
|
+
|
|
41
|
+
The full Swaps API v2 surface (quote, allowance, approve, create/submit/cancel intent, fees, gas, …) is wrapped one hook per endpoint under the `useSwapsApi*` prefix — see [hooks-index.md](../reference/hooks-index.md).
|
|
40
42
|
|
|
41
43
|
## Track Intent
|
|
42
44
|
|
|
@@ -126,19 +128,20 @@ const { data } = useBackendIntentByTxHash({
|
|
|
126
128
|
|
|
127
129
|
## Submit a Swap Tx
|
|
128
130
|
|
|
129
|
-
`
|
|
131
|
+
`useSwapsApiSubmitTx` is a mutation hook. The `request` is a `SubmitTxRequestV2`; per-call config (e.g. backend base URL) flows through `mutate(vars)`, and TanStack Query knobs through the optional `mutationOptions` slot:
|
|
130
132
|
|
|
131
133
|
```tsx
|
|
132
|
-
import {
|
|
134
|
+
import { useSwapsApiSubmitTx } from '@sodax/dapp-kit';
|
|
135
|
+
import type { SubmitTxRequestV2 } from '@sodax/sdk';
|
|
133
136
|
|
|
134
|
-
function SubmitButton({
|
|
135
|
-
const { mutateAsync: submitSwapTx, isPending } =
|
|
137
|
+
function SubmitButton({ request, baseURL }: { request: SubmitTxRequestV2; baseURL: string }) {
|
|
138
|
+
const { mutateAsync: submitSwapTx, isPending } = useSwapsApiSubmitTx({
|
|
136
139
|
mutationOptions: { retry: 5 }, // overrides default retry: 3
|
|
137
140
|
});
|
|
138
141
|
|
|
139
142
|
const handleSubmit = async () => {
|
|
140
143
|
const response = await submitSwapTx({
|
|
141
|
-
request
|
|
144
|
+
request,
|
|
142
145
|
apiConfig: { baseURL }, // per-call backend override
|
|
143
146
|
});
|
|
144
147
|
console.log('Submitted:', response);
|
|
@@ -148,10 +151,22 @@ function SubmitButton({ swapPayload, baseURL }) {
|
|
|
148
151
|
}
|
|
149
152
|
```
|
|
150
153
|
|
|
154
|
+
Poll the processing status with `useSwapsApiSubmitTxStatus` — it requires **both** `txHash` and `srcChainKey` (the v2 status endpoint needs the source chain key) and stops polling on `executed` / `failed`:
|
|
155
|
+
|
|
156
|
+
```tsx
|
|
157
|
+
import { useSwapsApiSubmitTxStatus } from '@sodax/dapp-kit';
|
|
158
|
+
|
|
159
|
+
function SwapStatus({ txHash, srcChainKey }: { txHash: string; srcChainKey: string }) {
|
|
160
|
+
const { data } = useSwapsApiSubmitTxStatus({ params: { txHash, srcChainKey } });
|
|
161
|
+
return <span>{data?.data?.status ?? 'idle'}</span>;
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
151
165
|
## Default Polling
|
|
152
166
|
|
|
153
167
|
| Hook | Interval |
|
|
154
168
|
|------|---------|
|
|
155
169
|
| `useBackendIntentByTxHash` | 1s |
|
|
170
|
+
| `useSwapsApiSubmitTxStatus` | 1s (stops on `executed` / `failed`) |
|
|
156
171
|
| `useBackendOrderbook` | none (`staleTime: 30s`, no auto-refetch) |
|
|
157
172
|
| Others | No auto-refresh |
|
|
@@ -208,5 +208,5 @@ function BnUSDMigration({ srcAddress }: { srcAddress: string }) {
|
|
|
208
208
|
|
|
209
209
|
- **ICX and BALN forward migrations** don't require approval — ICON has no ERC-20 allowance mechanism.
|
|
210
210
|
- **SODA → ICX revert** and **EVM/Stellar bnUSD sources** require approval before migrating.
|
|
211
|
-
- **BALN lock periods
|
|
211
|
+
- **BALN lock periods** (months → reward multiplier): `0` = 0.5x, `6` = 0.75x, `12` = 1.0x, `18` = 1.25x, `24` = 1.5x. Pass the `LockupPeriod` enum (whose values are in seconds), not the raw month number.
|
|
212
212
|
- `useMigratebnUSD` is bidirectional — swap `srcbnUSD`/`dstbnUSD` and `srcChainKey`/`dstChainKey` to go the other direction.
|
|
@@ -246,7 +246,7 @@ console.log({ swap, isError, error, swapsInFlight });
|
|
|
246
246
|
|
|
247
247
|
### Token list has duplicate addresses
|
|
248
248
|
|
|
249
|
-
`
|
|
249
|
+
`sodax.swaps.getSupportedSwapTokens()` returns `Record<SpokeChainKey, readonly XToken[]>`. Flattening it (e.g. `Object.values(...).flat()`) yields multiple tokens sharing the same contract address (same token on different chains). When rendering token lists, use a composite key like `${token.address}-${token.chainKey}` — not `token.address` alone. (`XToken` carries `chainKey`; there is no `blockchain_id` field.)
|
|
250
250
|
|
|
251
251
|
### Balance display
|
|
252
252
|
|
|
@@ -147,13 +147,11 @@ Comprehensive hook table across 12 feature domains. Use this when you know the f
|
|
|
147
147
|
| `useBackendIntentByHash` | none |
|
|
148
148
|
| `useBackendUserIntents` | none |
|
|
149
149
|
|
|
150
|
-
### Orderbook
|
|
150
|
+
### Orderbook
|
|
151
151
|
|
|
152
152
|
| Hook | Type / Polling |
|
|
153
153
|
|---|---|
|
|
154
154
|
| `useBackendOrderbook` | Query; `staleTime: 30s` — fresh-window only, no background refetch |
|
|
155
|
-
| `useBackendSubmitSwapTx` | Mutation |
|
|
156
|
-
| `useBackendSubmitSwapTxStatus` | Query; polls until `executed` / `failed` |
|
|
157
155
|
|
|
158
156
|
### Money market data
|
|
159
157
|
|
|
@@ -166,6 +164,46 @@ Comprehensive hook table across 12 feature domains. Use this when you know the f
|
|
|
166
164
|
| `useBackendMoneyMarketAssetBorrowers` | Borrowers for an asset |
|
|
167
165
|
| `useBackendAllMoneyMarketBorrowers` | All borrowers |
|
|
168
166
|
|
|
167
|
+
## Swaps API (`sodax.api.swaps`)
|
|
168
|
+
|
|
169
|
+
Typed React Query wrappers over the backend Swaps API v2 (`sodax.api.swaps.*`), one per endpoint. Distinct from the on-chain `swap/` hooks (`useQuote`/`useStatus`/`useSwap`/…), which drive `sodax.swaps` (the `SwapService`).
|
|
170
|
+
|
|
171
|
+
### Tokens · quote · fees · gas (reads)
|
|
172
|
+
|
|
173
|
+
| Hook | Type / Polling |
|
|
174
|
+
|---|---|
|
|
175
|
+
| `useSwapsApiTokens` | Query; all supported swap tokens by chain |
|
|
176
|
+
| `useSwapsApiTokensByChain` | Query; tokens for one chain |
|
|
177
|
+
| `useSwapsApiQuote` | Query; solver quote (set `query.includeTxData` for `txData`) |
|
|
178
|
+
| `useSwapsApiDeadline` | Query; computed swap deadline |
|
|
179
|
+
| `useSwapsApiPartnerFee` | Query; partner fee for an amount |
|
|
180
|
+
| `useSwapsApiSolverFee` | Query; protocol (solver) fee for an amount |
|
|
181
|
+
| `useSwapsApiEstimateGas` | Query; gas estimate for a raw tx |
|
|
182
|
+
|
|
183
|
+
### Intent lifecycle (reads)
|
|
184
|
+
|
|
185
|
+
| Hook | Type / Polling |
|
|
186
|
+
|---|---|
|
|
187
|
+
| `useSwapsApiAllowance` | Query; `{ valid }` allowance check |
|
|
188
|
+
| `useSwapsApiStatus` | Query (1s); polls until status `3` (SOLVED) / `4` (FAILED) |
|
|
189
|
+
| `useSwapsApiIntentHash` | Query; keccak256 of an intent struct |
|
|
190
|
+
| `useSwapsApiIntentPacket` | Query; long-polls the relayer for the fill packet (no client interval) |
|
|
191
|
+
| `useSwapsApiIntentExtraData` | Query; relay extra-data for submit |
|
|
192
|
+
| `useSwapsApiFilledIntent` | Query; on-chain fill state by tx hash |
|
|
193
|
+
| `useSwapsApiIntent` | Query; decoded intent struct by tx hash |
|
|
194
|
+
| `useSwapsApiSubmitTxStatus` | Query (1s); requires `txHash` + `srcChainKey`; polls until `executed` / `failed` |
|
|
195
|
+
|
|
196
|
+
### Actions (mutations)
|
|
197
|
+
|
|
198
|
+
| Hook | Type |
|
|
199
|
+
|---|---|
|
|
200
|
+
| `useSwapsApiApprove` | Mutation; builds unsigned approval tx |
|
|
201
|
+
| `useSwapsApiCreateIntent` | Mutation; builds `{ tx, intent, relayData }` |
|
|
202
|
+
| `useSwapsApiSubmitIntent` | Mutation; submits broadcast intent to the relay |
|
|
203
|
+
| `useSwapsApiCancelIntent` | Mutation; builds unsigned cancel tx |
|
|
204
|
+
| `useSwapsApiCreateLimitOrder` | Mutation; builds limit-order intent tx |
|
|
205
|
+
| `useSwapsApiSubmitTx` | Mutation; `request: SubmitTxRequestV2` |
|
|
206
|
+
|
|
169
207
|
## Partner
|
|
170
208
|
|
|
171
209
|
| Hook | Type | Purpose |
|
|
@@ -173,9 +211,13 @@ Comprehensive hook table across 12 feature domains. Use this when you know the f
|
|
|
173
211
|
| `useFetchAssetsBalances` | Query | Fetch partner asset balances |
|
|
174
212
|
| `useGetAutoSwapPreferences` | Query | Get auto-swap preferences |
|
|
175
213
|
| `useIsTokenApproved` | Query | Check token approval |
|
|
214
|
+
| `useGetUserIntent` | Query | Look up a partner's stored intent hash for a token pair (`0x0…0` = none) |
|
|
215
|
+
| `useGetIntentDetails` | Query | Read full intent details for an intent hash |
|
|
176
216
|
| `useApproveToken` | Mutation | Approve token |
|
|
177
217
|
| `useSetSwapPreference` | Mutation | Set swap preference |
|
|
178
218
|
| `useFeeClaimSwap` | Mutation | Claim partner fees via swap |
|
|
219
|
+
| `useFeeClaimWithdraw` | Mutation | Withdraw a fee token directly (no swap) via the bridge |
|
|
220
|
+
| `usePartnerCancelIntent` | Mutation | Cancel a stuck same-token claim and recover the locked tokens |
|
|
179
221
|
|
|
180
222
|
## Recovery
|
|
181
223
|
|
|
@@ -150,6 +150,38 @@ Skip if you're writing a feature hook for the first time and want to align with
|
|
|
150
150
|
| `['staking', 'cancelUnstake']` | `useCancelUnstake` |
|
|
151
151
|
| `['staking', 'approve', 'stake' \| 'unstake' \| 'instantUnstake']` | `useStakeApprove` / `useUnstakeApprove` / `useInstantUnstakeApprove` |
|
|
152
152
|
|
|
153
|
+
### Backend (read)
|
|
154
|
+
|
|
155
|
+
Backend read hooks (`useBackendIntentByTxHash`, `useBackendIntentByHash`, `useBackendUserIntents`, `useBackendOrderbook`, `useBackendMoneyMarketPosition`, …) follow the `['backend', action, ...]` shape — see the source hook files.
|
|
156
|
+
|
|
157
|
+
### Swaps API (`sodax.api.swaps`)
|
|
158
|
+
|
|
159
|
+
Typed wrappers over `sodax.api.swaps.*` (one per Swaps API v2 endpoint), all keyed `['swapsApi', action, ...]`.
|
|
160
|
+
|
|
161
|
+
| Key | Hook |
|
|
162
|
+
|---|---|
|
|
163
|
+
| `['swapsApi', 'tokens']` | `useSwapsApiTokens` |
|
|
164
|
+
| `['swapsApi', 'tokens', chainKey]` | `useSwapsApiTokensByChain` |
|
|
165
|
+
| `['swapsApi', 'quote', …]` | `useSwapsApiQuote` |
|
|
166
|
+
| `['swapsApi', 'deadline', …]` | `useSwapsApiDeadline` |
|
|
167
|
+
| `['swapsApi', 'allowance', …]` | `useSwapsApiAllowance` |
|
|
168
|
+
| `['swapsApi', 'status', …]` | `useSwapsApiStatus` |
|
|
169
|
+
| `['swapsApi', 'intentHash', …]` | `useSwapsApiIntentHash` |
|
|
170
|
+
| `['swapsApi', 'intentPacket', …]` | `useSwapsApiIntentPacket` |
|
|
171
|
+
| `['swapsApi', 'intentExtraData', …]` | `useSwapsApiIntentExtraData` |
|
|
172
|
+
| `['swapsApi', 'filledIntent', txHash]` | `useSwapsApiFilledIntent` |
|
|
173
|
+
| `['swapsApi', 'intent', txHash]` | `useSwapsApiIntent` |
|
|
174
|
+
| `['swapsApi', 'estimateGas', …]` | `useSwapsApiEstimateGas` |
|
|
175
|
+
| `['swapsApi', 'partnerFee', amount]` | `useSwapsApiPartnerFee` |
|
|
176
|
+
| `['swapsApi', 'solverFee', amount]` | `useSwapsApiSolverFee` |
|
|
177
|
+
| `['swapsApi', 'submitTx', 'status', txHash, srcChainKey]` | `useSwapsApiSubmitTxStatus` — both identifiers required |
|
|
178
|
+
| `['swapsApi', 'approve']` | `useSwapsApiApprove` mutation |
|
|
179
|
+
| `['swapsApi', 'createIntent']` | `useSwapsApiCreateIntent` mutation |
|
|
180
|
+
| `['swapsApi', 'submitIntent']` | `useSwapsApiSubmitIntent` mutation |
|
|
181
|
+
| `['swapsApi', 'cancelIntent']` | `useSwapsApiCancelIntent` mutation |
|
|
182
|
+
| `['swapsApi', 'createLimitOrder']` | `useSwapsApiCreateLimitOrder` mutation |
|
|
183
|
+
| `['swapsApi', 'submitTx']` | `useSwapsApiSubmitTx` mutation |
|
|
184
|
+
|
|
153
185
|
### Leverage Yield
|
|
154
186
|
|
|
155
187
|
| Key | Hook |
|
|
@@ -44,15 +44,17 @@ Read-only. No `walletProvider` involved. Convert to single-object query shape.
|
|
|
44
44
|
+ const { data: assets } = useBackendAllMoneyMarketAssets({});
|
|
45
45
|
```
|
|
46
46
|
|
|
47
|
-
`useBackendSubmitSwapTx` is a mutation — per-call config flows through `mutate(vars)
|
|
47
|
+
`useSwapsApiSubmitTx` (v1: `useBackendSubmitSwapTx` — renamed and moved into the `swapsApi/` namespace) is a mutation — per-call config flows through `mutate(vars)`. The v2 `request` is a `SubmitTxRequestV2` (`{ txHash, srcChainKey, walletAddress, intent, relayData }`):
|
|
48
48
|
|
|
49
49
|
```diff
|
|
50
50
|
- const submit = useBackendSubmitSwapTx({ baseURL: 'https://...' }); // v1: per-instance config
|
|
51
51
|
- await submit.mutateAsync(swapPayload);
|
|
52
|
-
+ const { mutateAsync: submit } =
|
|
52
|
+
+ const { mutateAsync: submit } = useSwapsApiSubmitTx();
|
|
53
53
|
+ await submit({ request: swapPayload, apiConfig: { baseURL: 'https://...' } }); // v2: per-call config
|
|
54
54
|
```
|
|
55
55
|
|
|
56
|
+
`useSwapsApiSubmitTxStatus` (v1: `useBackendSubmitSwapTxStatus`) now requires **both** `txHash` and `srcChainKey` (the v2 status endpoint needs the source chain key) — a v1 call that passed only a tx hash won't run until `srcChainKey` is supplied. The full Swaps API v2 surface is now wrapped as `useSwapsApi*` hooks (see the integration `hooks-index`).
|
|
57
|
+
|
|
56
58
|
## Shared utilities
|
|
57
59
|
|
|
58
60
|
### `useXBalances`
|
|
@@ -77,26 +79,26 @@ Note: the request param is still `xChainId` (not renamed to `chainKey`). This is
|
|
|
77
79
|
- const estimate = useEstimateGas(walletProvider);
|
|
78
80
|
- await estimate.mutateAsync({ rawTx });
|
|
79
81
|
+ const { mutateAsyncSafe: estimateGas } = useEstimateGas();
|
|
80
|
-
+ const result = await estimateGas({
|
|
82
|
+
+ const result = await estimateGas({ tx, chainKey }); // TVars is EstimateGasParams<C> = { tx, chainKey } — no walletProvider
|
|
81
83
|
```
|
|
82
84
|
|
|
83
85
|
### `useStellarTrustlineCheck` / `useRequestTrustline`
|
|
84
86
|
|
|
85
87
|
```diff
|
|
86
88
|
- const { data: hasTrustline } = useStellarTrustlineCheck(account, asset);
|
|
87
|
-
+ const { data: hasTrustline } = useStellarTrustlineCheck({ params: {
|
|
89
|
+
+ const { data: hasTrustline } = useStellarTrustlineCheck({ params: { token, amount, chainId, walletProvider } });
|
|
88
90
|
|
|
89
91
|
- const request = useRequestTrustline(walletProvider);
|
|
90
92
|
- await request.mutateAsync({ account, asset });
|
|
91
|
-
+ const {
|
|
92
|
-
+ await
|
|
93
|
+
+ const { requestTrustline } = useRequestTrustline(token); // positional token arg; NOT a mutation hook
|
|
94
|
+
+ await requestTrustline({ token, amount, srcChainKey, walletProvider });
|
|
93
95
|
```
|
|
94
96
|
|
|
95
97
|
### `useDeriveUserWalletAddress` / `useGetUserHubWalletAddress`
|
|
96
98
|
|
|
97
99
|
```diff
|
|
98
100
|
- const { data: hubAddress } = useDeriveUserWalletAddress(spokeChainKey, srcAddress);
|
|
99
|
-
+ const { data: hubAddress } = useDeriveUserWalletAddress({ params: {
|
|
101
|
+
+ const { data: hubAddress } = useDeriveUserWalletAddress({ params: { spokeChainId, spokeAddress } });
|
|
100
102
|
```
|
|
101
103
|
|
|
102
104
|
## Pitfalls
|
|
@@ -151,7 +151,7 @@ The hook equivalence in code:
|
|
|
151
151
|
1. **`useGetBridgeableAmount` data shape changed.** v1 returned bare `bigint`; v2 returns `Result<BridgeLimit>` where `BridgeLimit = { amount, decimals, type }`. UI code that displayed the bigint directly needs `.value.amount`.
|
|
152
152
|
2. **Tokens must share the same vault** to be bridgeable. Use `useGetBridgeableTokens` to enumerate compatible destinations — passing an incompatible pair to `bridge()` rejects with `VALIDATION_FAILED`.
|
|
153
153
|
3. **`useBridge` return is `TxHashPair`** — destructure as `{ srcChainTxHash, dstChainTxHash }`, not `[a, b]`.
|
|
154
|
-
4. **`recipient`
|
|
154
|
+
4. **`recipient` is NOT renamed.** It stays `recipient` in v2 (the destination receiver). Don't be tempted to rename it to `dstAddress` — that field shape lives on money-market params, not bridge. The genuinely new field is `srcAddress` (the spoke-side sender), which v1 didn't require.
|
|
155
155
|
|
|
156
156
|
## Cross-references
|
|
157
157
|
|
|
@@ -9,7 +9,7 @@ Pair: [`features/dex.md`](../../../integration/knowledge/features/dex.md).
|
|
|
9
9
|
1. **All mutations** (`useDexDeposit`, `useDexWithdraw`, `useSupplyLiquidity`, `useDecreaseLiquidity`, `useClaimRewards`, `useDexApprove`) — single-object hook init + `mutate({ params, walletProvider })`. SDK-leakage adds required `srcChainKey` + `srcAddress` to all action params.
|
|
10
10
|
2. **`useSupplyLiquidity` handles both mint-new and increase-existing** — pass `tokenId` in params for increase, omit for mint. Use `useCreateSupplyLiquidityParams` to handle the routing.
|
|
11
11
|
3. **`usePools` returns synchronously** in the SDK. The hook still returns `UseQueryResult` but the underlying call is config-derived (no RPC) — `staleTime: Infinity`, no auto-refresh.
|
|
12
|
-
4. **Param builders take a FLAT props object** — `useCreateDepositParams`, `useCreateWithdrawParams`, `useCreateSupplyLiquidityParams`, `useCreateDecreaseLiquidityParams` — NOT `{ params: { ... } }`-wrapped.
|
|
12
|
+
4. **Param builders take a FLAT props object** — `useCreateDepositParams`, `useCreateWithdrawParams`, `useCreateSupplyLiquidityParams`, `useCreateDecreaseLiquidityParams` — NOT `{ params: { ... } }`-wrapped. The builders take **no** `srcChainKey`/`srcAddress` input — you add those (using v2's `srcChainKey`, not v1's `srcChainId`) when spreading the builder's result into the mutation's `params` field at the call site.
|
|
13
13
|
|
|
14
14
|
## Per-method delta
|
|
15
15
|
|
|
@@ -52,7 +52,7 @@ These keep their name but their TypeScript signature is different. Usually requi
|
|
|
52
52
|
| `useRequestTrustline` | Custom utility hook (NOT a canonical mutation). Takes `(token: string \| undefined)` positionally, returns `{ requestTrustline, isLoading, isRequested, error, data }`. The `requestTrustline` callback takes `{ token, amount, srcChainKey, walletProvider }`. |
|
|
53
53
|
| `useBackendOrderbook` / `useBackendAllMoneyMarketBorrowers` | Pagination MUST be nested under `params`: `{ params: { pagination: { offset, limit } } }`. |
|
|
54
54
|
| `useBackendUserIntents` | Data is `UserIntentsResponse = { items: IntentResponse[], total, offset, limit }` — NOT a bare array. Access `data?.items`. |
|
|
55
|
-
| `useBackendSubmitSwapTx` |
|
|
55
|
+
| `useSwapsApiSubmitTx` / `useSwapsApiSubmitTxStatus` (v1: `useBackendSubmitSwapTx` / `useBackendSubmitSwapTxStatus`) | Renamed + moved to the `swapsApi/` namespace (keys now `['swapsApi', …]`). Mutation `apiConfig` moved from hook init to `mutate(vars)`; the status query now requires `srcChainKey`. The rest of the Swaps API v2 is newly wrapped as `useSwapsApi*` hooks. |
|
|
56
56
|
| All migration hooks | **NEW**: 6 per-action hooks replacing v1's single `useMigrate`. See [`deleted-hooks.md`](deleted-hooks.md). |
|
|
57
57
|
| `useMigrationAllowance` | Query params nest under `params` with inner field literally named `params` (NOT `payload`): `{ params: { params: <migration-params>, action: 'migrate' \| 'revert' } }`. |
|
|
58
58
|
| `BalnMigrateParams` (used by `useMigrateBaln`) | NEW required field `stake: boolean`. `lockupPeriod` is the `LockupPeriod` enum (5 members; values in seconds, not months). |
|
|
@@ -33,7 +33,7 @@ Granular skill for the lending/borrowing hooks of `@sodax/dapp-kit` v2. queryKey
|
|
|
33
33
|
- **Treating `useMMAllowance` `undefined` as "not approved" for borrow/withdraw.** The query is `enabled: false` for those actions — `undefined` means "approval not required."
|
|
34
34
|
- **Passing the MM params directly under `params` on `useMMAllowance`.** They nest under `params.payload`.
|
|
35
35
|
- **Treating mutation `data` as `Result<T>`.** `data` is the unwrapped `TxHashPair = { srcChainTxHash, dstChainTxHash }`.
|
|
36
|
-
- **Skipping a health-factor warning.**
|
|
36
|
+
- **Skipping a health-factor warning, or comparing it wrong.** `healthFactor` is a **string**, and a no-debt position returns the sentinel `'-1'` — so `Number(hf)` it and exclude `-1` before warning: `const hf = Number(summary.healthFactor); if (hf !== -1 && hf < 1.05) { /* warn */ }`. A raw `healthFactor < 1.05` is a TS error and would also flag a debt-free user.
|
|
37
37
|
|
|
38
38
|
## Migration workflow (port v1 MM hooks to v2)
|
|
39
39
|
|
|
@@ -34,7 +34,7 @@ Granular skill for the swap hooks of `@sodax/dapp-kit` v2. React-only — backen
|
|
|
34
34
|
- **Passing the SDK request directly under `params` on `useQuote`.** It nests under `params.payload` (a `SolverIntentQuoteRequest`). `useSwapAllowance` nests `payload` + `srcChainKey` + `walletProvider` under `params`.
|
|
35
35
|
- **Reading `data.status` on `useQuote` / `useStatus` without `data?.ok`.** Both return a `Result<…>` as their `data` — branch on `.ok` first. (`useSwapAllowance` is the opposite — already-unwrapped `boolean`.)
|
|
36
36
|
- **`useStatus` key is `intentTxHash`, not `intentHash`.**
|
|
37
|
-
- **Flattening `getSupportedSwapTokens()` and keying rows on `address`.** The same token address recurs across chains — use a composite `${address}-${
|
|
37
|
+
- **Flattening `getSupportedSwapTokens()` and keying rows on `address`.** The same token address recurs across chains — use a composite `${address}-${chainKey}` key (`XToken` carries `chainKey`, not `blockchain_id`).
|
|
38
38
|
- **Reaching for `useSpokeProvider`.** Deleted. Pass `walletProvider` into `mutate(vars)` for `useSwap`/`useSwapApprove`; cancel hooks take it flat.
|
|
39
39
|
|
|
40
40
|
## Migration workflow (port v1 swap hooks to v2)
|
|
@@ -55,7 +55,7 @@ Granular skill for the swap hooks of `@sodax/dapp-kit` v2. React-only — backen
|
|
|
55
55
|
## Related granular skills (same family)
|
|
56
56
|
|
|
57
57
|
- [`../money-market/SKILL.md`](../money-market/SKILL.md) — if the swap feeds a supply/borrow action.
|
|
58
|
-
- [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — `
|
|
58
|
+
- [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — `useSwapsApiSubmitTx` / intent-tracking + orderbook reads (step-by-step swap + diagnostics), partner fee-claim swaps.
|
|
59
59
|
|
|
60
60
|
For tasks spanning multiple features, load the broad [`sodax-dapp-kit` skill](../SKILL.md) instead.
|
|
61
61
|
|
|
@@ -33,7 +33,8 @@ If the user has already picked a single feature, load the matching granular skil
|
|
|
33
33
|
| ICX / bnUSD / BALN token migration to SODAX | [`./migration/SKILL.md`](./migration/SKILL.md) | "migrate ICX", "legacy bnUSD", "BALN lockup" (NOT v1→v2 SDK porting) |
|
|
34
34
|
| Partner fees | [`./partner/SKILL.md`](./partner/SKILL.md) | "claim partner fee", "partner auto-swap preference", "approve partner fee token" |
|
|
35
35
|
| Stuck-asset recovery | [`./recovery/SKILL.md`](./recovery/SKILL.md) | "recover stuck assets on Sonic", "RecoveryService", "withdrawHubAsset" |
|
|
36
|
-
| Backend HTTP client (intents, orderbook, MM reads) | [`./backend-api/SKILL.md`](./backend-api/SKILL.md) | "
|
|
36
|
+
| Backend HTTP client (intents, orderbook, MM reads) | [`./backend-api/SKILL.md`](./backend-api/SKILL.md) | "getIntentByHash", "Sodax backend API", "orderbook", "custom IConfigApiV1" |
|
|
37
|
+
| 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" |
|
|
37
38
|
|
|
38
39
|
Load this broad skill (keep reading below) when:
|
|
39
40
|
|
|
@@ -55,7 +56,7 @@ This skill documents the **SDK call sites** — what to import, how to construct
|
|
|
55
56
|
|
|
56
57
|
- **Multi-user state** (Telegram bot per-user wallets, dApp session storage, custodial vs non-custodial design). Hold one wallet-provider instance per user/chain at the app layer and pass it into each call — the SDK is stateless.
|
|
57
58
|
- **UI**, framework wiring, route handlers, webhooks. Pick your own framework (telegraf/grammy for bots, Next.js / Vite for web, etc.) — the SDK has no opinion.
|
|
58
|
-
- **Token discovery beyond `sodax.config`**. The SDK exposes `sodax.config.findSupportedTokenBySymbol(chainKey, symbol)` for per-chain lookups and `sodax.bridge.getBridgeableTokens(from, to,
|
|
59
|
+
- **Token discovery beyond `sodax.config`**. The SDK exposes `sodax.config.findSupportedTokenBySymbol(chainKey, symbol)` for per-chain lookups and `sodax.bridge.getBridgeableTokens(from, to, token)` / `sodax.bridge.isBridgeable({ from, to })` for vault-pair checks. There is no exhaustive "all bridgeable pairs across all chains" table — derive it at runtime if needed.
|
|
59
60
|
|
|
60
61
|
If the consumer needs a runnable end-to-end app (Node bot, CLI, full dApp), the right combination is: this skill (for SDK call sites) + `sodax-wallet-sdk-core` (for wallet providers) + the consumer's chosen framework code. The SDK does not ship an app skeleton.
|
|
61
62
|
|
|
@@ -75,7 +76,7 @@ Follow in order. Skipping `ai-rules.md` is the most common cause of agents rever
|
|
|
75
76
|
|
|
76
77
|
1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DO NOT / workflow / stop conditions.
|
|
77
78
|
2. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — install, initialize, first-run troubleshooting.
|
|
78
|
-
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`, `backend-api.md`.
|
|
79
|
+
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`, `backend-api.md`, `swaps-api.md`.
|
|
79
80
|
4. For specific patterns (init, raw vs signed, chain narrowing, gas, testing, errors, logging), read [`integration/knowledge/recipes/`](./integration/knowledge/recipes/).
|
|
80
81
|
5. Lookups (chain keys, error codes, public API surface, wallet provider types, glossary) → [`integration/knowledge/reference/`](./integration/knowledge/reference/).
|
|
81
82
|
6. Non-EVM quirks (Stellar trustline, BTC PSBT, Solana PDA, ICON, NEAR) → [`integration/knowledge/chain-specifics.md`](./integration/knowledge/chain-specifics.md).
|
|
@@ -110,7 +111,7 @@ If the consumer has v1 fingerprints AND also wants new features: **do migration
|
|
|
110
111
|
1. Read [`migration-v1-to-v2/knowledge/ai-rules.md`](./migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT / workflow / stop conditions. **Read first** — prevents the most common porting mistakes.
|
|
111
112
|
2. Read [`migration-v1-to-v2/knowledge/README.md`](./migration-v1-to-v2/knowledge/README.md) — overview, reading order, cross-cutting checklist, v1↔v2 glossary.
|
|
112
113
|
3. **Cross-cutting first.** In order:
|
|
113
|
-
- [`breaking-changes/type-system.md`](./migration-v1-to-v2/knowledge/breaking-changes/type-system.md) — renames at `@sodax/types`, `ChainKeys`, `WalletProviderSlot`, `RpcConfig`, `
|
|
114
|
+
- [`breaking-changes/type-system.md`](./migration-v1-to-v2/knowledge/breaking-changes/type-system.md) — renames at `@sodax/types`, `ChainKeys`, `WalletProviderSlot`, `RpcConfig`, `IConfigApiV1` Result.
|
|
114
115
|
- [`breaking-changes/architecture.md`](./migration-v1-to-v2/knowledge/breaking-changes/architecture.md) — `*SpokeProvider` deletion, `ConfigService`, relay reshape.
|
|
115
116
|
- [`breaking-changes/result-and-errors.md`](./migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md) — throws → `Result<T>`; module errors → `SodaxError<C>`; v1↔v2 code crosswalk.
|
|
116
117
|
4. **Per-feature playbooks** under [`features/`](./migration-v1-to-v2/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `partner.md`, `recovery.md`, `backend-api.md` — read only the ones the consumer uses.
|