@sodax/skills 2.0.0-rc.9 → 2.0.0
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/.claude-plugin/plugin.json +1 -9
- package/AGENTS.md +119 -14
- package/README.md +5 -2
- package/package.json +1 -1
- package/skills/sodax-build/SKILL.md +90 -0
- package/skills/sodax-build/knowledge/README.md +35 -0
- package/skills/sodax-build/knowledge/brief-template.md +41 -0
- package/skills/sodax-build/knowledge/chains-and-assets.md +26 -0
- package/skills/sodax-build/knowledge/example-sessions.md +84 -0
- package/skills/sodax-build/knowledge/feature-catalog.md +51 -0
- package/skills/sodax-build/knowledge/glossary.md +35 -0
- package/skills/sodax-build/knowledge/handoff.md +60 -0
- package/skills/sodax-build/knowledge/interview-guide.md +66 -0
- package/skills/sodax-build/knowledge/monetization.md +37 -0
- package/skills/sodax-build/knowledge/use-case-gallery.md +32 -0
- package/skills/sodax-dapp-kit/SKILL.md +6 -2
- package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +65 -0
- package/skills/sodax-dapp-kit/bitcoin/SKILL.md +57 -0
- package/skills/sodax-dapp-kit/bridge/SKILL.md +59 -0
- package/skills/sodax-dapp-kit/dex/SKILL.md +60 -0
- package/skills/sodax-dapp-kit/integration/knowledge/README.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/README.md +3 -2
- package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +71 -11
- package/skills/sodax-dapp-kit/integration/knowledge/features/bitcoin.md +10 -6
- package/skills/sodax-dapp-kit/integration/knowledge/features/dex.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +112 -0
- package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +6 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md +8 -8
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +168 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +4 -4
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md +3 -0
- package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +67 -6
- package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +49 -0
- package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +54 -0
- package/skills/sodax-dapp-kit/migration/SKILL.md +64 -0
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +2 -2
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +19 -10
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md +2 -2
- 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 +3 -3
- package/skills/sodax-dapp-kit/money-market/SKILL.md +61 -0
- package/skills/sodax-dapp-kit/staking/SKILL.md +60 -0
- package/skills/sodax-dapp-kit/swap/SKILL.md +64 -0
- package/skills/sodax-sdk/SKILL.md +11 -6
- package/skills/sodax-sdk/backend-api/SKILL.md +21 -15
- package/skills/sodax-sdk/bridge/SKILL.md +4 -0
- package/skills/sodax-sdk/dex/SKILL.md +5 -1
- package/skills/sodax-sdk/integration/knowledge/README.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/architecture.md +24 -21
- package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
- package/skills/sodax-sdk/integration/knowledge/features/README.md +2 -1
- package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +27 -16
- package/skills/sodax-sdk/integration/knowledge/features/bridge.md +15 -14
- package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
- package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +175 -0
- package/skills/sodax-sdk/integration/knowledge/features/migration.md +73 -28
- package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
- 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 +42 -24
- package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
- package/skills/sodax-sdk/integration/knowledge/quickstart.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -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 +34 -2
- package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +102 -0
- package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +28 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
- 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 +40 -4
- package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +32 -9
- package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
- package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -4
- package/skills/sodax-sdk/leverage-yield/SKILL.md +50 -0
- package/skills/sodax-sdk/migration/SKILL.md +5 -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 +3 -3
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -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 +18 -16
- package/skills/sodax-sdk/money-market/SKILL.md +7 -3
- package/skills/sodax-sdk/partner/SKILL.md +4 -0
- package/skills/sodax-sdk/recovery/SKILL.md +5 -1
- package/skills/sodax-sdk/staking/SKILL.md +4 -0
- package/skills/sodax-sdk/swap/SKILL.md +8 -3
- package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
- package/skills/sodax-wallet-sdk-core/SKILL.md +7 -3
- package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/evm/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/icon/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/injective/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +2 -2
- 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/evm.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/quickstart.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/recipes/testing.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
- 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/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/near/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/solana/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/stacks/SKILL.md +53 -0
- package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/sui/SKILL.md +53 -0
- package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
- package/skills/sodax-wallet-sdk-react/bridge-to-sdk/SKILL.md +56 -0
- package/skills/sodax-wallet-sdk-react/connect/SKILL.md +59 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
- 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 +10 -10
- 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 +4 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/ssr-setup.md +24 -19
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +1 -1
- package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +51 -0
- package/skills/sodax-wallet-sdk-react/switch-chain/SKILL.md +51 -0
- package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-react/walletconnect/SKILL.md +52 -0
|
@@ -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)`.
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
// @ai-snippets-skip
|
|
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
|
|
76
|
+
```
|
|
77
|
+
|
|
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 }`):
|
|
68
79
|
|
|
69
80
|
```ts
|
|
70
81
|
// @ai-snippets-skip
|
|
71
|
-
|
|
72
|
-
|
|
82
|
+
const { mutateAsync: submitSwapTx } = useSwapsApiSubmitTx();
|
|
83
|
+
// request: SubmitTxRequestV2 — relayData is the string payload; intent carries bigint fields
|
|
84
|
+
await submitSwapTx({ request, apiConfig: { baseURL: 'https://...' } });
|
|
73
85
|
```
|
|
74
86
|
|
|
75
|
-
`
|
|
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:
|
|
76
88
|
|
|
77
89
|
```ts
|
|
78
90
|
// @ai-snippets-skip
|
|
79
|
-
const {
|
|
80
|
-
|
|
91
|
+
const { data: status } = useSwapsApiSubmitTxStatus({ params: { txHash, srcChainKey } });
|
|
92
|
+
// status?.data?.status: 'pending' | 'relaying' | 'relayed' | 'posting_execution' | 'posted_execution' | 'solved' | 'failed'
|
|
81
93
|
```
|
|
82
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.
|
|
@@ -94,6 +108,10 @@ useGetUserHubWalletAddress({ params, queryOptions }); // Hub wallet via wallet r
|
|
|
94
108
|
useEstimateGas({ mutationOptions }); // Gas estimation for raw tx
|
|
95
109
|
useStellarTrustlineCheck({ params, queryOptions });
|
|
96
110
|
useRequestTrustline({ mutationOptions });
|
|
111
|
+
useNearStorageCheck({ params, queryOptions }); // NEP-141 storage registration check (NEAR)
|
|
112
|
+
useRegisterNearStorage({ mutationOptions }); // NEP-141 storage_deposit (NEAR)
|
|
113
|
+
useNearStorageGate({ dstChainKey, token, accountId, walletProvider }); // composite NEAR receive-side gate
|
|
114
|
+
resolveNearStorageGate(chainKey, check); // unwrapped util: gate-state from a useNearStorageCheck result
|
|
97
115
|
```
|
|
98
116
|
|
|
99
117
|
### `useXBalances` shape
|
|
@@ -125,11 +143,12 @@ Stellar accounts that have never held an asset have no trustline — receiving w
|
|
|
125
143
|
|
|
126
144
|
```ts
|
|
127
145
|
// @ai-snippets-skip — illustrative only; real types pulled into agents below.
|
|
128
|
-
// useStellarTrustlineCheck
|
|
129
|
-
// `
|
|
130
|
-
//
|
|
146
|
+
// useStellarTrustlineCheck reads a trustline (no signing). Pass the resolved Stellar account
|
|
147
|
+
// `walletAddress` (e.g. useXAccount('STELLAR').address) — it keys the cache per account, so the
|
|
148
|
+
// verdict is never reused across accounts. `chainId` is a `SpokeChainKey` (typed loosely — the hook
|
|
149
|
+
// returns `true` for non-Stellar chains, making it safe to gate on conditionally).
|
|
131
150
|
const { data: hasTrustline } = useStellarTrustlineCheck({
|
|
132
|
-
params: { token, amount, chainId: ChainKeys.STELLAR_MAINNET,
|
|
151
|
+
params: { token, amount, chainId: ChainKeys.STELLAR_MAINNET, walletAddress },
|
|
133
152
|
});
|
|
134
153
|
|
|
135
154
|
// useRequestTrustline is NOT a canonical mutation hook — it takes a single positional
|
|
@@ -144,12 +163,53 @@ if (hasTrustline === false) {
|
|
|
144
163
|
}
|
|
145
164
|
```
|
|
146
165
|
|
|
166
|
+
### NEAR storage registration
|
|
167
|
+
|
|
168
|
+
NEP-141 accounts must pay a one-time storage bond before they can receive a token — delivering to an unregistered account fails. The receive-side analogue of Stellar trustlines: gate any flow that delivers a token to the user on NEAR (swap output on NEAR, bridge into NEAR, money-market borrow/withdraw to NEAR). Use `useNearStorageGate` for app UI; use the lower-level `useNearStorageCheck` + `useRegisterNearStorage` pair when you need custom wiring.
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
// @ai-snippets-skip — illustrative only; real types pulled into agents below.
|
|
172
|
+
// useNearStorageCheck is a canonical read hook: { params: { token, accountId, chainId }, queryOptions }.
|
|
173
|
+
// `chainId` is a SpokeChainKey typed loosely — the hook returns `true` for non-NEAR chains (safe to
|
|
174
|
+
// gate conditionally) and `true` for native NEAR (not a NEP-141 token). data is a boolean;
|
|
175
|
+
// queryKey: ['shared', 'nearStorageCheck', chainId, token, accountId].
|
|
176
|
+
const { data: isRegistered, isLoading } = useNearStorageCheck({
|
|
177
|
+
params: { token, accountId, chainId: ChainKeys.NEAR_MAINNET },
|
|
178
|
+
});
|
|
179
|
+
|
|
180
|
+
// useRegisterNearStorage IS a canonical mutation hook: { mutationOptions }, returns
|
|
181
|
+
// SafeUseMutationResult. Domain inputs flow through mutate / mutateAsync / mutateAsyncSafe.
|
|
182
|
+
// Vars: { token, accountId, walletProvider, deposit? } — deposit defaults to the NEP-141
|
|
183
|
+
// storage bond (0.00125 NEAR). mutationKey: ['shared', 'registerNearStorage'].
|
|
184
|
+
const { mutateAsyncSafe: registerStorage } = useRegisterNearStorage();
|
|
185
|
+
if (isRegistered === false) {
|
|
186
|
+
await registerStorage({ token, accountId, walletProvider });
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
For the common UI path, `useNearStorageGate` returns `{ isNear, needsRegistration, blocksAction, isChecking, isRegistering, registerStorage }`.
|
|
191
|
+
|
|
192
|
+
Derive UI gate flags with the unwrapped `resolveNearStorageGate` util (no hook) when you need custom check/register composition:
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
// @ai-snippets-skip — illustrative only.
|
|
196
|
+
// resolveNearStorageGate(chainKey, check) reads `isLoading` + `data` off the useNearStorageCheck
|
|
197
|
+
// result and returns { isNear, needsRegistration, blocksAction }:
|
|
198
|
+
// needsRegistration — show the register action (check resolved AND not registered)
|
|
199
|
+
// blocksAction — keep the downstream action disabled (still checking OR needs registration)
|
|
200
|
+
const check = useNearStorageCheck({ params: { token, accountId, chainId: dstChainKey } });
|
|
201
|
+
const { needsRegistration, blocksAction } = resolveNearStorageGate(dstChainKey, check);
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
The underlying SDK methods (`isStorageRegistered` / `registerStorage` on the NEAR spoke service, and the `NEAR_STORAGE_DEPOSIT` constant) are documented in the `sodax-sdk` skill (integration mode).
|
|
205
|
+
|
|
147
206
|
## Default polling intervals
|
|
148
207
|
|
|
149
208
|
| Hook | Polling | Notes |
|
|
150
209
|
|---|---|---|
|
|
151
210
|
| `useBackendIntentByTxHash` | 1s | once a `txHash` is supplied (refetch is unconditional, not "while pending") |
|
|
152
|
-
| `
|
|
211
|
+
| `useSwapsApiSubmitTxStatus` | 1s | requires `txHash` + `srcChainKey`; stops on `solved` / `failed` |
|
|
212
|
+
| `useSwapsApiStatus` | 1s | solver intent status; stops on status `3` / `4` |
|
|
153
213
|
| `useBackendOrderbook` | none | `staleTime: 30s` — fresh-window, no background refetch |
|
|
154
214
|
| `useExpiredUtxos` (bitcoin) | 60s | refetchInterval |
|
|
155
215
|
| `useQuote` (swap) | 3s | refetchInterval |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# Bitcoin (
|
|
1
|
+
# Bitcoin (Bound Exchange) — `@sodax/dapp-kit`
|
|
2
2
|
|
|
3
|
-
Bitcoin trading via the
|
|
3
|
+
Bitcoin trading via the Bound Exchange protocol — authenticate, fund a trading wallet, withdraw, manage UTXOs. **Dapp-kit-unique surface** (no SDK equivalent — these flows are React-shaped).
|
|
4
4
|
|
|
5
5
|
Pair: [`features/bitcoin.md`](../../../migration-v1-to-v2/knowledge/features/bitcoin.md).
|
|
6
6
|
|
|
@@ -11,11 +11,12 @@ Pair: [`features/bitcoin.md`](../../../migration-v1-to-v2/knowledge/features/bit
|
|
|
11
11
|
// Session lifecycle
|
|
12
12
|
useRadfiAuth({ mutationOptions }); // Authenticate via BIP322 signing
|
|
13
13
|
useRadfiSession(walletProvider); // Manage full lifecycle (login, refresh, auto-refresh)
|
|
14
|
+
useEnsureRadfiAccessToken({ mutationOptions }); // Ensure a fresh Bound token; resolves to the token string
|
|
14
15
|
useTradingWallet(walletAddress); // Synchronous: read persisted session
|
|
15
16
|
|
|
16
17
|
// Balances
|
|
17
18
|
useBitcoinBalance({ params: { address, rpcUrl? }, queryOptions }); // Personal wallet (default mempool.space)
|
|
18
|
-
useTradingWalletBalance({ params: { walletProvider, tradingAddress }, queryOptions }); //
|
|
19
|
+
useTradingWalletBalance({ params: { walletProvider, tradingAddress }, queryOptions }); // Bound Exchange API
|
|
19
20
|
|
|
20
21
|
// Operations
|
|
21
22
|
useFundTradingWallet({ mutationOptions });
|
|
@@ -24,9 +25,11 @@ useExpiredUtxos({ params: { walletProvider, tradingAddress }, queryOptions }); /
|
|
|
24
25
|
useRenewUtxos({ mutationOptions });
|
|
25
26
|
```
|
|
26
27
|
|
|
28
|
+
`useEnsureRadfiAccessToken` is for raw / server-side `createIntent`: it resolves a valid Bound token to forward as `extras.bound.accessToken` (the Bitcoin-gated `bound` slot) on a `raw: true` swap intent, or as `bound.accessToken` on a backend createIntent DTO. See the `sodax-sdk` skill (swap feature) for the `extras.bound` slot.
|
|
29
|
+
|
|
27
30
|
## Session flow
|
|
28
31
|
|
|
29
|
-
|
|
32
|
+
Bound Exchange requires authentication before trading operations. `useRadfiSession` handles the full lifecycle:
|
|
30
33
|
|
|
31
34
|
```ts
|
|
32
35
|
// @ai-snippets-skip
|
|
@@ -63,6 +66,7 @@ type RenewUtxosVars = { txIdVouts: string[]; walletProvider: IBitcoinWalletProvi
|
|
|
63
66
|
| Hook | Returns |
|
|
64
67
|
|---|---|
|
|
65
68
|
| `useRadfiAuth` | `SafeUseMutationResult<RadfiAuthResult, Error, UseRadfiAuthVars>` where `RadfiAuthResult = { accessToken, refreshToken, tradingAddress }` (3 fields, NOT `RadfiSession` — the hook persists `publicKey` to localStorage internally but doesn't return it) |
|
|
69
|
+
| `useEnsureRadfiAccessToken` | `SafeUseMutationResult<string, Error, { walletProvider }>` — resolves to a valid Bound Exchange access token (silent refresh when possible, else BIP322 re-auth) |
|
|
66
70
|
| `useFundTradingWallet` | `SafeUseMutationResult<TxId, Error, ...>` |
|
|
67
71
|
| `useRadfiWithdraw` | `SafeUseMutationResult<{ txId, fee }, Error, ...>` |
|
|
68
72
|
| `useRenewUtxos` | `SafeUseMutationResult<TxId, Error, ...>` |
|
|
@@ -76,8 +80,8 @@ type RenewUtxosVars = { txIdVouts: string[]; walletProvider: IBitcoinWalletProvi
|
|
|
76
80
|
|
|
77
81
|
1. **Authentication required before any trading operation.** `useRadfiSession` manages this automatically — gate buttons on `isAuthed`.
|
|
78
82
|
2. **Trading wallet is created during first authentication** — not a separate step.
|
|
79
|
-
3. **`useTradingWallet(walletAddress)` is synchronous** (no network call). It reads persisted
|
|
80
|
-
4. **PSBT signing flow for withdrawals.**
|
|
83
|
+
3. **`useTradingWallet(walletAddress)` is synchronous** (no network call). It reads persisted Bound Exchange session from localStorage. Use it when you don't have a `walletProvider` available yet but need the trading address.
|
|
84
|
+
4. **PSBT signing flow for withdrawals.** Bound Exchange server builds an unsigned PSBT, the user signs locally via the wallet provider, then submits back for co-signing and broadcast. The dapp-kit hook orchestrates this — consumers don't see PSBTs directly.
|
|
81
85
|
5. **Session tokens are for API rate-limiting, not asset access.** Stored in localStorage keyed by wallet address. Compromise of localStorage data doesn't affect funds.
|
|
82
86
|
6. **`useExpiredUtxos` polls every 60s** — set `queryOptions.refetchInterval: false` to disable while UI is hidden.
|
|
83
87
|
|
|
@@ -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
|
```
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
# Leverage Yield — `@sodax/dapp-kit`
|
|
2
|
+
|
|
3
|
+
Leveraged-yield ERC-4626 vaults on the Sonic hub. Deposit any token → `lsoda*` vault shares, withdraw shares → any token; plus position / APR / TVL / share-balance reads. New in v2 (no v1 equivalent).
|
|
4
|
+
|
|
5
|
+
## Hook surface
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
// @ai-snippets-skip
|
|
9
|
+
// Mutations
|
|
10
|
+
useLeverageYieldDeposit({ mutationOptions }); // build a deposit payload (any token → lsoda*)
|
|
11
|
+
useLeverageYieldWithdraw({ mutationOptions }); // build a withdraw payload (lsoda* → any token; hubWalletSwap)
|
|
12
|
+
useLeverageYieldVaultSwap({ mutationOptions }); // EXECUTE the built payload end-to-end
|
|
13
|
+
useLeverageYieldNotifySolver({ mutationOptions }); // manual-flow: notify the solver after a self-driven relay
|
|
14
|
+
|
|
15
|
+
// Reads
|
|
16
|
+
useLeverageYieldEffectiveApr({ params, queryOptions }); // AAVE + LSD effective net APR (60s)
|
|
17
|
+
useLeverageYieldPosition({ params, queryOptions }); // collateral/debt/ltv/healthFactor/idle (30s)
|
|
18
|
+
useLeverageYieldTotalAssets({ params, queryOptions }); // vault TVL, 18-dp bigint (60s)
|
|
19
|
+
useLeverageYieldPreviewRedeem({ params, queryOptions }); // assets for N shares; price-per-share (60s)
|
|
20
|
+
useLeverageYieldShareBalances({ params, queryOptions }); // per-chain share balances via useQueries (15s)
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
`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
|
+
## Mutation TVars
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
// @ai-snippets-skip
|
|
29
|
+
// deposit — vars are the SDK's deposit params (any token → lsoda* on the hub wallet)
|
|
30
|
+
type UseLeverageYieldDepositVars = LeverageYieldSwapDepositParams;
|
|
31
|
+
// { vault: Address; srcChainKey; srcAddress; inputToken; inputAmount: bigint;
|
|
32
|
+
// minOutputAmount: bigint; deadline?: bigint; solver?: Address; partnerFee? }
|
|
33
|
+
|
|
34
|
+
// withdraw — lsoda* shares → any token on any chain (hub-wallet sourced)
|
|
35
|
+
type UseLeverageYieldWithdrawVars = LeverageYieldSwapWithdrawParams;
|
|
36
|
+
// { vault: Address; srcChainKey; srcAddress; dstChainKey; outputToken;
|
|
37
|
+
// inputAmount: bigint; minOutputAmount: bigint; recipient?; deadline?; solver? }
|
|
38
|
+
|
|
39
|
+
// vaultSwap — the executor. Spread the built payload + walletProvider.
|
|
40
|
+
type UseLeverageYieldVaultSwapVars<K> = Omit<VaultSwapActionParams<K, false>, 'raw'>;
|
|
41
|
+
// = SpokeExecActionParams<K, false, CreateIntentParams<K>> & { hubWalletSwap?; partnerFee? }
|
|
42
|
+
// i.e. { params: CreateIntentParams<K>; walletProvider; hubWalletSwap?; partnerFee?; timeout? }
|
|
43
|
+
|
|
44
|
+
// notifySolver — manual-flow notify step (vaultSwap already notifies internally)
|
|
45
|
+
type UseLeverageYieldNotifySolverVars = SolverExecutionRequest;
|
|
46
|
+
// { intent_tx_hash: Hex } — the hub-side tx hash where the intent landed
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Read shapes (key picks)
|
|
50
|
+
|
|
51
|
+
```ts
|
|
52
|
+
// @ai-snippets-skip
|
|
53
|
+
// useLeverageYieldEffectiveApr — AAVE rates + LSD staking yield, leverage re-applied (data unwrapped)
|
|
54
|
+
useLeverageYieldEffectiveApr({ params: { vault } })
|
|
55
|
+
// → UseQueryResult<LeverageYieldEffectiveApr>
|
|
56
|
+
// LeverageYieldEffectiveApr = LeverageYieldApr & { lsdApr, effectiveSupplyAprRay, effectiveNetAprRay }
|
|
57
|
+
// LeverageYieldApr = { supplyAprRay, borrowAprRay, targetLtvBps, leverageMultiplierWad, netAprRay } (RAY = 1e27)
|
|
58
|
+
|
|
59
|
+
// useLeverageYieldPosition — live position snapshot
|
|
60
|
+
useLeverageYieldPosition({ params: { vault } })
|
|
61
|
+
// → UseQueryResult<LeverageYieldPosition>
|
|
62
|
+
// LeverageYieldPosition = { collateral, debt, ltv, healthFactor, idleAsset } (all bigint)
|
|
63
|
+
|
|
64
|
+
// useLeverageYieldPreviewRedeem — assets per shares; pass 1e18 for price-per-share
|
|
65
|
+
useLeverageYieldPreviewRedeem({ params: { vault, shares: 10n ** 18n } })
|
|
66
|
+
// → UseQueryResult<bigint>
|
|
67
|
+
|
|
68
|
+
// useLeverageYieldShareBalances — returns an ARRAY (one query per holder), NOT a single result
|
|
69
|
+
useLeverageYieldShareBalances({ params: { vault, holders } })
|
|
70
|
+
// → UseQueryResult<LeverageYieldShareHolding>[]
|
|
71
|
+
// LeverageYieldShareHolding = { chainKey: SpokeChainKey; holder: Address; shares: bigint }
|
|
72
|
+
// holders: { chainKey: SpokeChainKey; address: string }[] — one row per chain the user may hold under
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Approval pattern
|
|
76
|
+
|
|
77
|
+
Leverage-yield has **no dedicated approve hook**. A deposit is a swap-style intent that bridges `inputToken` from the spoke chain, so it approves the spoke-side asset manager exactly like a swap — reuse the swap hooks. A withdraw needs no spoke-side approval: the payload carries `hubWalletSwap: true` and `vaultSwap` authorises the hub wallet to spend the `lsoda*` shares via a `Connection.sendMessage` the user signs on `srcChainKey`.
|
|
78
|
+
|
|
79
|
+
| Flow | Token approved | Hook |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| `deposit` | spoke `inputToken` → asset manager | `useSwapApprove`, `useSwapAllowance` (swap domain) |
|
|
82
|
+
| `withdraw` | none (hub-wallet `sendMessage` authorises the spend) | — |
|
|
83
|
+
|
|
84
|
+
## Return shapes
|
|
85
|
+
|
|
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`.
|
|
87
|
+
|
|
88
|
+
| Hook | Returns |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `useLeverageYieldDeposit` / `useLeverageYieldWithdraw` | `SafeUseMutationResult<LeverageYieldSwapPayload, Error, …>` (builder — `data` is the payload to spread into `useLeverageYieldVaultSwap`) |
|
|
91
|
+
| `useLeverageYieldVaultSwap` | `SafeUseMutationResult<VaultSwapResponse, Error, …>` (`{ solverExecutionResponse, intent, intentDeliveryInfo }`) |
|
|
92
|
+
| `useLeverageYieldNotifySolver` | `SafeUseMutationResult<SolverExecutionResponse, Error, …>` (`{ answer: 'OK', intent_hash }`) |
|
|
93
|
+
| `useLeverageYieldEffectiveApr` | `UseQueryResult<LeverageYieldEffectiveApr, Error>` |
|
|
94
|
+
| `useLeverageYieldPosition` | `UseQueryResult<LeverageYieldPosition, Error>` |
|
|
95
|
+
| `useLeverageYieldTotalAssets` | `UseQueryResult<bigint, Error>` |
|
|
96
|
+
| `useLeverageYieldPreviewRedeem` | `UseQueryResult<bigint, Error>` |
|
|
97
|
+
| `useLeverageYieldShareBalances` | `UseQueryResult<LeverageYieldShareHolding, Error>[]` (array — one entry per holder) |
|
|
98
|
+
|
|
99
|
+
## Gotchas
|
|
100
|
+
|
|
101
|
+
1. **`deposit` / `withdraw` are builders, not executors.** Their `data` is a `LeverageYieldSwapPayload` — spread it into `useLeverageYieldVaultSwap`'s `mutate` with a `walletProvider` to actually run the swap. Calling them does not broadcast anything.
|
|
102
|
+
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
|
+
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
|
+
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.
|
|
106
|
+
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
|
+
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
|
+
|
|
109
|
+
## Cross-references
|
|
110
|
+
|
|
111
|
+
- [`../recipes/leverage-yield.md`](../recipes/leverage-yield.md) — full worked deposit / withdraw / reads examples.
|
|
112
|
+
- For the underlying SDK leverage-yield surface (`LeverageYieldService`, `createVaultIntent`, `notifySolver`, APR math), load the `sodax-sdk` skill (integration mode) — its `features/leverage-yield.md`.
|
|
@@ -43,6 +43,8 @@ type UseUserFormattedSummaryParams = ReadHookParams<FormatUserSummaryResponse, {
|
|
|
43
43
|
userAddress: string | undefined;
|
|
44
44
|
}>;
|
|
45
45
|
// Same shape on useUserReservesData. The hook derives the hub wallet from (spokeChainKey, userAddress) internally.
|
|
46
|
+
// Bitcoin: always pass the personal address as userAddress — the hook transparently resolves to the
|
|
47
|
+
// Bound Exchange trading-wallet-derived hub wallet when a session is active (local lookup, no network).
|
|
46
48
|
|
|
47
49
|
// useAToken — single aToken metadata; FLAT (no chain/user fields)
|
|
48
50
|
type UseATokenParams = ReadHookParams<ATokenData, {
|
|
@@ -57,10 +59,13 @@ type UseATokensBalancesParams = ReadHookParams<Map<Address, bigint>, {
|
|
|
57
59
|
userAddress: string | undefined;
|
|
58
60
|
}>;
|
|
59
61
|
// Returns a Map keyed by aToken address. The hook resolves the hub wallet from (spokeChainKey, userAddress).
|
|
62
|
+
// Bitcoin: always pass the personal address — trading-wallet resolution is automatic when a session exists.
|
|
60
63
|
```
|
|
61
64
|
|
|
62
65
|
> **Read-side chain key is `spokeChainKey`, not `srcChainKey`.** Mutation hooks (`useSupply`/`useBorrow`/etc.) use `srcChainKey` because the request crosses chains and needs a source. Read hooks describe a user's position on a single spoke chain — the field is `spokeChainKey`. Applies to `useATokensBalances`, `useUserFormattedSummary`, and `useUserReservesData` (`useAToken` is metadata-only and takes neither). Don't grep-replace one for the other.
|
|
63
66
|
|
|
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
|
+
|
|
64
69
|
## Mutation params
|
|
65
70
|
|
|
66
71
|
All four user mutations share the same TVars shape (only the `action` literal differs):
|
|
@@ -132,7 +137,7 @@ if (!isApproved) await approve({ params: supplyParams, walletProvider });
|
|
|
132
137
|
|
|
133
138
|
## Gotchas
|
|
134
139
|
|
|
135
|
-
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).
|
|
136
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).
|
|
137
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.
|
|
138
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
|
|
|
@@ -21,11 +21,11 @@ pnpm add @sodax/wallet-sdk-react
|
|
|
21
21
|
import { QueryClientProvider } from '@tanstack/react-query';
|
|
22
22
|
import { SodaxProvider, createSodaxQueryClient } from '@sodax/dapp-kit';
|
|
23
23
|
import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
|
|
24
|
-
import { ChainKeys, type
|
|
24
|
+
import { ChainKeys, type SodaxOptions } from '@sodax/sdk';
|
|
25
25
|
|
|
26
26
|
const queryClient = createSodaxQueryClient();
|
|
27
27
|
|
|
28
|
-
const sodaxConfig:
|
|
28
|
+
const sodaxConfig: SodaxOptions = {
|
|
29
29
|
chains: {
|
|
30
30
|
[ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://sonic-rpc.publicnode.com' },
|
|
31
31
|
[ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
|
|
@@ -35,6 +35,7 @@ Copy-paste patterns for adding SODAX features to a React app. Each recipe is sel
|
|
|
35
35
|
| [`staking.md`](staking.md) | `useStake`, `useUnstake`, `useClaim`, staking info, ratios |
|
|
36
36
|
| [`migration.md`](migration.md) | `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln` |
|
|
37
37
|
| [`dex.md`](dex.md) | `useDexDeposit`, `useSupplyLiquidity`, positions, pools |
|
|
38
|
+
| [`leverage-yield.md`](leverage-yield.md) | `useLeverageYieldDeposit`, `useLeverageYieldWithdraw`, `useLeverageYieldVaultSwap`, APR/position/TVL/share-balance reads |
|
|
38
39
|
| [`bitcoin.md`](bitcoin.md) | `useRadfiSession`, `useFundTradingWallet`, `useRadfiWithdraw`, UTXO management |
|
|
39
40
|
| [`backend-queries.md`](backend-queries.md) | Intent tracking, orderbook, money market position queries (read-only, no wallet) |
|
|
40
41
|
|
|
@@ -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 `solved` / `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 `solved` / `failed`) |
|
|
156
171
|
| `useBackendOrderbook` | none (`staleTime: 30s`, no auto-refetch) |
|
|
157
172
|
| Others | No auto-refresh |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
# Recipe: Bitcoin (
|
|
1
|
+
# Recipe: Bitcoin (Bound Exchange)
|
|
2
2
|
|
|
3
|
-
Bitcoin trading via the
|
|
3
|
+
Bitcoin trading via the Bound Exchange protocol. Authenticate, fund a trading wallet, trade, withdraw, and manage UTXOs.
|
|
4
4
|
|
|
5
5
|
**Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
|
|
6
6
|
|
|
@@ -10,7 +10,7 @@ Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, tra
|
|
|
10
10
|
|
|
11
11
|
| Hook | Type | Purpose |
|
|
12
12
|
|------|------|---------|
|
|
13
|
-
| `useRadfiAuth` | Mutation | Authenticate with
|
|
13
|
+
| `useRadfiAuth` | Mutation | Authenticate with Bound Exchange via BIP322 signing |
|
|
14
14
|
| `useRadfiSession` | Utility | Manage full session lifecycle (login, refresh, auto-refresh) |
|
|
15
15
|
| `useTradingWallet` | Utility | Get trading wallet address from persisted session (synchronous) |
|
|
16
16
|
|
|
@@ -19,7 +19,7 @@ Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, tra
|
|
|
19
19
|
| Hook | Type | Purpose |
|
|
20
20
|
|------|------|---------|
|
|
21
21
|
| `useBitcoinBalance` | Query | BTC balance for any address (sums UTXOs from mempool.space) |
|
|
22
|
-
| `useTradingWalletBalance` | Query | Trading wallet balance from
|
|
22
|
+
| `useTradingWalletBalance` | Query | Trading wallet balance from Bound Exchange API (confirmed + pending) |
|
|
23
23
|
|
|
24
24
|
### Operations
|
|
25
25
|
|
|
@@ -32,7 +32,7 @@ Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, tra
|
|
|
32
32
|
|
|
33
33
|
## Session Flow
|
|
34
34
|
|
|
35
|
-
|
|
35
|
+
Bound Exchange requires authentication before any trading operation. The typical flow:
|
|
36
36
|
|
|
37
37
|
```tsx
|
|
38
38
|
import { useRadfiSession } from '@sodax/dapp-kit';
|
|
@@ -49,7 +49,7 @@ function BitcoinAuth() {
|
|
|
49
49
|
|
|
50
50
|
return (
|
|
51
51
|
<button onClick={login} disabled={isLoginPending}>
|
|
52
|
-
{isLoginPending ? 'Signing...' : 'Login to
|
|
52
|
+
{isLoginPending ? 'Signing...' : 'Login to Bound Exchange'}
|
|
53
53
|
</button>
|
|
54
54
|
);
|
|
55
55
|
}
|
|
@@ -77,7 +77,7 @@ function BitcoinBalances({ walletAddress }: { walletAddress: string }) {
|
|
|
77
77
|
params: { address: walletAddress },
|
|
78
78
|
});
|
|
79
79
|
|
|
80
|
-
// Trading wallet balance (from
|
|
80
|
+
// Trading wallet balance (from Bound Exchange API). `RadfiWalletBalance` fields:
|
|
81
81
|
// `btcSatoshi`, `pendingSatoshi`, `externalPendingSatoshi`, `totalUtxos`.
|
|
82
82
|
const { data: tradingBalance } = useTradingWalletBalance({
|
|
83
83
|
params: { walletProvider, tradingAddress },
|
|
@@ -188,6 +188,6 @@ function UtxoManager({ tradingAddress }: { tradingAddress: string }) {
|
|
|
188
188
|
|
|
189
189
|
- **Authentication required** before any trading operation. `useRadfiSession` manages this automatically.
|
|
190
190
|
- **Trading wallet** is created during first authentication — not a separate step.
|
|
191
|
-
- **`useTradingWallet(walletAddress)`** is a synchronous utility (no network call) — it reads the persisted
|
|
191
|
+
- **`useTradingWallet(walletAddress)`** is a synchronous utility (no network call) — it reads the persisted Bound Exchange session from localStorage.
|
|
192
192
|
- **PSBT signing flow**: withdraw and renew operations build an unsigned PSBT server-side, user signs it locally, then submits back for co-signing and broadcast.
|
|
193
193
|
- **Session tokens** are stored in localStorage keyed by wallet address. They're for API rate-limiting, not for accessing user assets.
|