@sodax/skills 2.0.0-rc.8 → 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 -0
- package/AGENTS.md +123 -13
- 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/migration.md +1 -1
- 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/features/migration.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 +54 -50
- package/skills/sodax-sdk/backend-api/SKILL.md +58 -0
- package/skills/sodax-sdk/bridge/SKILL.md +53 -0
- package/skills/sodax-sdk/dex/SKILL.md +54 -0
- package/skills/sodax-sdk/integration/knowledge/README.md +5 -3
- package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/architecture.md +26 -39
- package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
- package/skills/sodax-sdk/integration/knowledge/features/README.md +6 -3
- package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +92 -0
- package/skills/sodax-sdk/integration/knowledge/features/bridge.md +48 -11
- 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/{icx-bnusd-baln.md → migration.md} +75 -30
- package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
- package/skills/sodax-sdk/integration/knowledge/features/partner.md +86 -0
- package/skills/sodax-sdk/integration/knowledge/features/recovery.md +51 -0
- package/skills/sodax-sdk/integration/knowledge/features/staking.md +8 -3
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +106 -22
- 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 +69 -0
- 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 +6 -10
- 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 +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/README.md +4 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +92 -0
- 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/{icx-bnusd-baln.md → migration.md} +31 -29
- 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 +64 -0
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +35 -0
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +8 -3
- 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 +19 -17
- package/skills/sodax-sdk/money-market/SKILL.md +56 -0
- package/skills/sodax-sdk/partner/SKILL.md +55 -0
- package/skills/sodax-sdk/recovery/SKILL.md +53 -0
- package/skills/sodax-sdk/staking/SKILL.md +53 -0
- package/skills/sodax-sdk/swap/SKILL.md +72 -0
- 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
- package/skills/sodax-sdk/integration/knowledge/features/auxiliary-services.md +0 -189
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/auxiliary-services.md +0 -156
|
@@ -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,33 @@ 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
|
-
-
|
|
87
|
-
|
|
88
|
+
- // Positional args; `destProvider` carried both the signer and the destination chain.
|
|
89
|
+
- const { data: hasTrustline } = useStellarTrustlineCheck(token, amount, destProvider, dstChainId);
|
|
90
|
+
+ // Single `params` object. Pass the resolved Stellar address (e.g. useXAccount('STELLAR').address),
|
|
91
|
+
+ // NOT a provider — the address keys the cache per account.
|
|
92
|
+
+ const { data: hasTrustline } = useStellarTrustlineCheck({
|
|
93
|
+
+ params: { token, amount, chainId, walletAddress },
|
|
94
|
+
+ });
|
|
88
95
|
|
|
89
|
-
-
|
|
90
|
-
- await
|
|
91
|
-
+
|
|
92
|
-
+
|
|
96
|
+
- // The callback took a `spokeProvider`.
|
|
97
|
+
- await requestTrustline({ token, amount, spokeProvider: destProvider });
|
|
98
|
+
+ // useRequestTrustline is NOT a canonical mutation: the token is positional, and it returns a
|
|
99
|
+
+ // `requestTrustline` callback that now takes `srcChainKey` + `walletProvider`.
|
|
100
|
+
+ const { requestTrustline } = useRequestTrustline(token);
|
|
101
|
+
+ await requestTrustline({ token, amount, srcChainKey, walletProvider });
|
|
93
102
|
```
|
|
94
103
|
|
|
95
104
|
### `useDeriveUserWalletAddress` / `useGetUserHubWalletAddress`
|
|
96
105
|
|
|
97
106
|
```diff
|
|
98
107
|
- const { data: hubAddress } = useDeriveUserWalletAddress(spokeChainKey, srcAddress);
|
|
99
|
-
+ const { data: hubAddress } = useDeriveUserWalletAddress({ params: {
|
|
108
|
+
+ const { data: hubAddress } = useDeriveUserWalletAddress({ params: { spokeChainId, spokeAddress } });
|
|
100
109
|
```
|
|
101
110
|
|
|
102
111
|
## Pitfalls
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
# Bitcoin (
|
|
1
|
+
# Bitcoin (Bound Exchange) migration — v1 → v2 (dapp-kit)
|
|
2
2
|
|
|
3
3
|
Pair: [`features/bitcoin.md`](../../../integration/knowledge/features/bitcoin.md).
|
|
4
4
|
|
|
5
|
-
Bitcoin /
|
|
5
|
+
Bitcoin / Bound Exchange hook surface was new in v1 with limited adoption; v2 standardizes its shapes against the canonical hook conventions. Treat the v2 forms below as the canonical reference — if your v1 code used a different shape, swap to v2's directly.
|
|
6
6
|
|
|
7
7
|
## TL;DR
|
|
8
8
|
|
|
@@ -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
|
|
|
@@ -117,4 +117,4 @@ The biggest single API change in dapp-kit v2: v1 had a single `useMigrate(spokeP
|
|
|
117
117
|
|
|
118
118
|
- [`features/migration.md`](../../../integration/knowledge/features/migration.md) — v2 reference.
|
|
119
119
|
- [`recipes/migration.md`](../../../integration/knowledge/recipes/migration.md) — full v2 worked examples (ICX, BALN, bnUSD, revert).
|
|
120
|
-
- `sodax-sdk`: `migration-v1-to-v2/knowledge/features/
|
|
120
|
+
- `sodax-sdk`: `migration-v1-to-v2/knowledge/features/migration.md` — underlying SDK migration migration.
|
|
@@ -48,18 +48,18 @@ These keep their name but their TypeScript signature is different. Usually requi
|
|
|
48
48
|
| `useXBalances` | Params: positional → `{ params: { xService, xChainId, xTokens, address } }`. All four required. `xService` injected from `@sodax/wallet-sdk-react`. |
|
|
49
49
|
| `useEstimateGas` | Mutation; vars: `EstimateGasParams<C>` (flat, not `{ params, walletProvider }`-wrapped). |
|
|
50
50
|
| `useDeriveUserWalletAddress`, `useGetUserHubWalletAddress` | Single-object query shape. |
|
|
51
|
-
| `useStellarTrustlineCheck` | Single-object shape
|
|
51
|
+
| `useStellarTrustlineCheck` | Single-object shape under `params`: `{ token, amount, chainId, walletAddress }`. Pass the resolved Stellar address (e.g. `useXAccount('STELLAR').address`), not a wallet provider — it keys the cache per account. |
|
|
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). |
|
|
59
59
|
| `useTradingWalletBalance` | Return is `RadfiWalletBalance = { btcSatoshi, pendingSatoshi, externalPendingSatoshi, totalUtxos }` — NOT `{ confirmed, pending }`. |
|
|
60
60
|
| `useExpiredUtxos` | Return is `RadfiUtxo[]` (with `_id`, `txid`, `vout`, `txidVout`, `satoshi`, `amount`, `address`, `isSpent`, `status`, `source`, optional `runes`). Both this and `useTradingWalletBalance` take `{ params: { walletProvider, tradingAddress } }`. |
|
|
61
61
|
| `useRadfiAuth` | TData is `RadfiAuthResult = { accessToken, refreshToken, tradingAddress }` (3 fields — `publicKey` is persisted to localStorage but NOT returned). |
|
|
62
|
-
| All Bitcoin/
|
|
62
|
+
| All Bitcoin/Bound Exchange mutations | Standard pattern — drop hook-init args; pass through `mutate(vars)`. |
|
|
63
63
|
|
|
64
64
|
## Cross-references
|
|
65
65
|
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-dapp-kit-money-market
|
|
3
|
+
description: 'Granular skill for the @sodax/dapp-kit v2 money-market feature only — React Query hooks for cross-chain lending/borrowing: useSupply, useBorrow, useWithdraw, useRepay, useMMAllowance, useMMApprove, plus reserves/position reads (useReservesHumanized, useUserFormattedSummary, useUserReservesData, useAToken, useATokensBalances). Use when a React dapp task is specifically money-market (e.g. "useSupply with dapp-kit", "borrow hook", "render health factor in React", "Sodax lending hooks", "withdraw collateral hook"). Covers BOTH integration (new v2 hooks) and migration (port v1 MM hooks — single-object params, srcChainKey/srcAddress required, mutateAsyncSafe). Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Money Market (dapp-kit granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for the lending/borrowing hooks of `@sodax/dapp-kit` v2. queryKey/mutationKey first segment: `mm`. React-only — backend uses `@sodax/sdk` directly.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
1. **New code or v1 → v2 port?**
|
|
17
|
+
2. **Which action?** `useSupply`, `useBorrow`, `useWithdraw`, `useRepay`, or read-only (reserves / user position).
|
|
18
|
+
3. **Same-chain or cross-chain delivery?** All four actions accept optional `dstChainKey`/`dstAddress` (omit for same-chain; don't pass `dstChainKey === srcChainKey`).
|
|
19
|
+
4. **Need allowance gating?** `supply`/`repay` need approval (`useMMAllowance` + `useMMApprove`); `borrow`/`withdraw` never need ERC-20 approval (`useMMAllowance` is `enabled: false` for those → `data` stays `undefined`).
|
|
20
|
+
5. **Need position reads?** Reserve data (`useReservesHumanized` etc.) and user position (`useUserFormattedSummary`, `useUserReservesData`) — read hooks key on `spokeChainKey`, not `srcChainKey`.
|
|
21
|
+
|
|
22
|
+
## Integration workflow (new v2 code)
|
|
23
|
+
|
|
24
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
|
|
25
|
+
2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
|
|
26
|
+
3. [`../integration/knowledge/features/money-market.md`](../integration/knowledge/features/money-market.md) — full hook surface, mutation TVars (`{ params: MoneyMarketSupplyParams<K>, walletProvider }`), reserve/position read shapes, the `spokeChainKey` vs `srcChainKey` split.
|
|
27
|
+
4. [`../integration/knowledge/recipes/money-market.md`](../integration/knowledge/recipes/money-market.md) — full worked examples.
|
|
28
|
+
5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
|
|
29
|
+
|
|
30
|
+
### Money-market-specific anti-patterns (dapp-kit)
|
|
31
|
+
|
|
32
|
+
- **Using `srcChainKey`/`srcAddress` on read hooks.** Those are mutation-side names. Position reads (`useATokensBalances`, `useUserFormattedSummary`, `useUserReservesData`) key on `spokeChainKey` + `userAddress`; the hub wallet is derived automatically. Don't grep-replace one for the other.
|
|
33
|
+
- **Treating `useMMAllowance` `undefined` as "not approved" for borrow/withdraw.** The query is `enabled: false` for those actions — `undefined` means "approval not required."
|
|
34
|
+
- **Passing the MM params directly under `params` on `useMMAllowance`.** They nest under `params.payload`.
|
|
35
|
+
- **Treating mutation `data` as `Result<T>`.** `data` is the unwrapped `TxHashPair = { srcChainTxHash, dstChainTxHash }`.
|
|
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
|
+
|
|
38
|
+
## Migration workflow (port v1 MM hooks to v2)
|
|
39
|
+
|
|
40
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
|
|
41
|
+
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) — `srcChainKey`/`srcAddress` now required.
|
|
42
|
+
3. [`../migration-v1-to-v2/knowledge/features/money-market.md`](../migration-v1-to-v2/knowledge/features/money-market.md) — add `srcChainKey`/`srcAddress` to every action; allowance auto-skip for borrow/withdraw.
|
|
43
|
+
4. `invalidateMmQueries` and friends are gone — hooks own their invalidations. See [`../migration-v1-to-v2/knowledge/reference/deleted-hooks.md`](../migration-v1-to-v2/knowledge/reference/deleted-hooks.md).
|
|
44
|
+
|
|
45
|
+
## Verification
|
|
46
|
+
|
|
47
|
+
1. `pnpm tsc --noEmit` clean.
|
|
48
|
+
2. Mutation flows use `mutateAsyncSafe` and branch on `result.ok`.
|
|
49
|
+
3. Read hooks use `spokeChainKey`/`userAddress` (not `srcChainKey`/`srcAddress`).
|
|
50
|
+
4. No `invalidateMmQueries`, no `useSpokeProvider` (migration only).
|
|
51
|
+
|
|
52
|
+
## Related granular skills (same family)
|
|
53
|
+
|
|
54
|
+
- [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — backend MM data reads (`useBackendMoneyMarketPosition`, suppliers/borrowers lists) that don't need a wallet.
|
|
55
|
+
- [`../swap/SKILL.md`](../swap/SKILL.md) — when supplying collateral that requires an upstream swap.
|
|
56
|
+
|
|
57
|
+
For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
|
|
58
|
+
|
|
59
|
+
## Wallet connectivity (different SDK package family)
|
|
60
|
+
|
|
61
|
+
`walletProvider` flows through `mutate(vars)` for the action hooks. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets and get a typed `walletProvider` via `useWalletProvider({ xChainId: chainKey })`.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-dapp-kit-staking
|
|
3
|
+
description: 'Granular skill for the @sodax/dapp-kit v2 staking feature only — React Query hooks for SODA ↔ xSODA staking: useStake, useUnstake, useInstantUnstake, useClaim, useCancelUnstake, the three dedicated approve/allowance hook pairs (stake/unstake/instantUnstake), plus reads (useStakingInfo, useUnstakingInfoWithPenalty, useStakingConfig, useStakeRatio). Use when a React dapp task is specifically staking (e.g. "useStake with dapp-kit", "unstake hook with penalty", "claim staking rewards in React", "instant unstake slippage hook", "render staking info"). Covers BOTH integration (new v2 hooks) and migration (port v1 staking hooks — single-object params, useStakeRatio now returns a tuple, mutateAsyncSafe). Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Staking (dapp-kit granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for the staking hooks of `@sodax/dapp-kit` v2. queryKey/mutationKey first segment: `staking`. React-only — backend uses `@sodax/sdk` directly.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
1. **New code or v1 → v2 port?**
|
|
17
|
+
2. **Which action?** `useStake`, `useUnstake` (waiting period), `useInstantUnstake` (slippage, no wait), `useClaim`, `useCancelUnstake`.
|
|
18
|
+
3. **Allowance gating?** `stake` approves SODA, `unstake`/`instantUnstake` approve xSODA — each has its OWN approve + allowance hook pair. `claim`/`cancelUnstake` need no approval.
|
|
19
|
+
4. **Need reads?** `useStakingInfo` (position), `useUnstakingInfoWithPenalty` (pending requests + penalty), `useStakingConfig` (protocol params), `useStakeRatio`/`useInstantUnstakeRatio` (previews).
|
|
20
|
+
|
|
21
|
+
## Integration workflow (new v2 code)
|
|
22
|
+
|
|
23
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
|
|
24
|
+
2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
|
|
25
|
+
3. [`../integration/knowledge/features/staking.md`](../integration/knowledge/features/staking.md) — full hook surface, mutation TVars per action, the three approve/allowance pairs, read shapes.
|
|
26
|
+
4. [`../integration/knowledge/recipes/staking.md`](../integration/knowledge/recipes/staking.md) — full worked examples.
|
|
27
|
+
5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
|
|
28
|
+
|
|
29
|
+
### Staking-specific anti-patterns (dapp-kit)
|
|
30
|
+
|
|
31
|
+
- **Treating `useStakeRatio` `data` as a single bigint.** It's a 2-tuple `[xSodaAmount, previewDepositAmount]` (already unwrapped) — index `data?.[0]` / `data?.[1]`.
|
|
32
|
+
- **Branching on `data.ok` for staking reads.** All staking read hooks are already unwrapped (the hook throws on SDK `!ok`). Read `data` fields directly; surface SDK failures via `isError`/`error`.
|
|
33
|
+
- **Reading the request id at `req.request.requestId`.** On `useUnstakingInfoWithPenalty`, access `data?.requestsWithPenalty` directly; the id is `req.id`.
|
|
34
|
+
- **One global approve hook.** There are three — `useStakeApprove` (SODA), `useUnstakeApprove` (xSODA), `useInstantUnstakeApprove` (xSODA). Pick the one matching the action.
|
|
35
|
+
- **Treating instant unstake as free.** It bypasses the wait but pays slippage — preview with `useInstantUnstakeRatio`, set `minAmount`.
|
|
36
|
+
|
|
37
|
+
## Migration workflow (port v1 staking hooks to v2)
|
|
38
|
+
|
|
39
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
|
|
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/staking.md`](../migration-v1-to-v2/knowledge/features/staking.md) — all five mutations + their dedicated approve hooks; `useStakeRatio` now returns a tuple.
|
|
42
|
+
|
|
43
|
+
## Verification
|
|
44
|
+
|
|
45
|
+
1. `pnpm tsc --noEmit` clean.
|
|
46
|
+
2. Mutation flows use `mutateAsyncSafe` and branch on `result.ok`.
|
|
47
|
+
3. `useStakeRatio` consumers index the tuple (`data?.[0]`), not a scalar.
|
|
48
|
+
4. Staking reads read `data` directly (no `.ok`/`.value`).
|
|
49
|
+
5. No `useSpokeProvider`, no hook-level `spokeProvider` (migration only).
|
|
50
|
+
|
|
51
|
+
## Related granular skills (same family)
|
|
52
|
+
|
|
53
|
+
- [`../migration/SKILL.md`](../migration/SKILL.md) — BALN → SODA migration can auto-stake (`stake: true`); use it for BALN lock flows.
|
|
54
|
+
- [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — `useXBalances` / gas-estimation utilities used alongside staking UI.
|
|
55
|
+
|
|
56
|
+
For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
|
|
57
|
+
|
|
58
|
+
## Wallet connectivity (different SDK package family)
|
|
59
|
+
|
|
60
|
+
`walletProvider` flows through `mutate(vars)`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets and get a typed `walletProvider` via `useWalletProvider({ xChainId: chainKey })`.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-dapp-kit-swap
|
|
3
|
+
description: 'Granular skill for the @sodax/dapp-kit v2 swap feature only — React Query hooks for intent-based cross-chain swaps via the solver: useSwap, useQuote, useSwapAllowance, useSwapApprove, useStatus, useCreateLimitOrder, useCancelSwap, useCancelLimitOrder. Use when a React dapp has decided the task is a swap (e.g. "useSwap with dapp-kit", "Sodax React swap hook", "limit order hook", "poll swap status", "cancel a Sodax intent in React") and you want to skip loading the broad sodax-dapp-kit skill. Covers BOTH integration (write new v2 hooks) and migration (port v1 swap hooks to v2 — single-object params, mutateAsyncSafe, hook-owned invalidations). Picks via Step 1. Links into the parent sodax-dapp-kit knowledge tree. For backend/Node swaps (no React), use the sodax-sdk skill instead.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Swap (dapp-kit granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for the swap hooks of `@sodax/dapp-kit` v2. React-only — backend/Node swaps use `@sodax/sdk` directly. Source-of-truth reference lives in the parent broad skill's knowledge tree; this file is the focused workflow only.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
1. **New code or v1 → v2 port?**
|
|
17
|
+
- New → § Integration workflow.
|
|
18
|
+
- Port v1 → § Migration workflow.
|
|
19
|
+
2. **Which hooks?** Quote/preview (`useQuote`), execute (`useSwap`), allowance gate (`useSwapAllowance` + `useSwapApprove`), status polling (`useStatus`), or limit orders (`useCreateLimitOrder` / `useCancelLimitOrder`).
|
|
20
|
+
3. **Market order or limit order?** Limit orders use `useCreateLimitOrder` (no `deadline`; cancel manually via `useCancelLimitOrder`).
|
|
21
|
+
4. **Imperative flow or render-driven?** Sequenced flows → `mutateAsyncSafe` (returns `Result<T>`, never rejects). Fire-and-forget → `mutate`.
|
|
22
|
+
|
|
23
|
+
## Integration workflow (new v2 code)
|
|
24
|
+
|
|
25
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first; skipping it is the top cause of reverting to v1 hook shapes).
|
|
26
|
+
2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `SafeUseMutationResult`, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
|
|
27
|
+
3. [`../integration/knowledge/features/swap.md`](../integration/knowledge/features/swap.md) — full hook surface, param shapes (`useQuote`/`useSwapAllowance` nest under `params.payload`; cancel hooks are FLAT), return shapes, polling intervals.
|
|
28
|
+
4. [`../integration/knowledge/recipes/swap.md`](../integration/knowledge/recipes/swap.md) — full worked example.
|
|
29
|
+
5. Call-shape choice (`mutate` / `mutateAsync` / `mutateAsyncSafe`) → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
|
|
30
|
+
|
|
31
|
+
### Swap-specific anti-patterns (dapp-kit)
|
|
32
|
+
|
|
33
|
+
- **Treating `useSwap` `data` as `Result<T>`.** The hook's `mutationFn` unwraps before resolving — `data` is the success value (`SwapResponse = { intent, intentDeliveryInfo, solverExecutionResponse }`). For SDK `!ok` read `mutation.error` or use `mutateAsyncSafe` for the `Result<T>` shape.
|
|
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
|
+
- **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
|
+
- **`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}-${chainKey}` key (`XToken` carries `chainKey`, not `blockchain_id`).
|
|
38
|
+
- **Reaching for `useSpokeProvider`.** Deleted. Pass `walletProvider` into `mutate(vars)` for `useSwap`/`useSwapApprove`; cancel hooks take it flat.
|
|
39
|
+
|
|
40
|
+
## Migration workflow (port v1 swap hooks to v2)
|
|
41
|
+
|
|
42
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
|
|
43
|
+
2. Cross-cutting deltas, in order: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md) (single-arg policy), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md) (`mutateAsyncSafe`), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
|
|
44
|
+
3. [`../migration-v1-to-v2/knowledge/features/swap.md`](../migration-v1-to-v2/knowledge/features/swap.md) — v1 `useSwap(spokeProvider)`-style call sites → v2 `mutate({ params, walletProvider })`; approve return-shape change.
|
|
45
|
+
4. The SDK underneath also changed — also load the `sodax-sdk` skill (migration mode) for the raw swap-layer port.
|
|
46
|
+
|
|
47
|
+
## Verification
|
|
48
|
+
|
|
49
|
+
1. `pnpm tsc --noEmit` from the consumer repo exits clean.
|
|
50
|
+
2. Sequenced swap flows use `mutateAsyncSafe` and branch on `result.ok` (user-reject is modal, not exceptional).
|
|
51
|
+
3. `useQuote` / `useStatus` call sites branch on `data?.ok` before reading status fields.
|
|
52
|
+
4. No `useSpokeProvider`, no hook-level `spokeProvider`/`params` (migration only).
|
|
53
|
+
5. React Query devtools show hook-owned invalidations firing on success (consumer `onSuccess` runs after).
|
|
54
|
+
|
|
55
|
+
## Related granular skills (same family)
|
|
56
|
+
|
|
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) — `useSwapsApiSubmitTx` / intent-tracking + orderbook reads (step-by-step swap + diagnostics), partner fee-claim swaps.
|
|
59
|
+
|
|
60
|
+
For tasks spanning multiple features, load the broad [`sodax-dapp-kit` skill](../SKILL.md) instead.
|
|
61
|
+
|
|
62
|
+
## Wallet connectivity (different SDK package family)
|
|
63
|
+
|
|
64
|
+
This skill treats `walletProvider` as an input flowing through `mutate(vars)`. Every dapp-kit consumer needs wallet connectivity — **also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets and get a typed `walletProvider` per chain via `useWalletProvider({ xChainId: chainKey })`.
|
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-sdk
|
|
3
|
-
description: '
|
|
3
|
+
description: 'Integrate SODAX cross-chain DeFi into a backend, Node script, bot, indexer, or non-React app with @sodax/sdk — swaps, lending/borrowing, staking, bridging, concentrated-liquidity DEX, ICX/bnUSD/BALN token migration, partner fees, and stuck-asset recovery across Sonic (hub) + 20 spoke chains. INTEGRATION (write NEW v2 code) — hub-and-spoke architecture across EVM and non-EVM chains; covers intent-based swaps, lending/borrowing (money market), staking, bridging, concentrated-liquidity DEX, token migration, partner fees, and stuck-asset recovery. Use whenever a non-React or backend codebase calls `@sodax/sdk` directly (Node scripts, indexers, bots, server APIs, custom non-React browser flows). Triggers on "use @sodax/sdk", "swap with Sodax", "Sodax bridge", "Sodax money market", "Sodax staking", "cross-chain DeFi", "Sonic hub", any `Sodax` / `ChainKeys` / `Result<T>` / `SodaxError` symbol. For React dapps, prefer `sodax-dapp-kit` instead. MIGRATION (port v1 → v2) — the v2 reshape replaced `*SpokeProvider` classes with chain-key-driven routing, throws with `Result<T>`, module-specific error unions with `SodaxError<C>`, ad-hoc wallet/raw branching with `WalletProviderSlot<K, Raw>`, and static lookup tables with `ConfigService`. Triggers on "migrate Sodax v1", "upgrade @sodax/sdk", "v1 → v2", "useSpokeProvider broken", "Sodax error types changed", v1 fingerprints (`_MAINNET_CHAIN_ID`, `*SpokeProvider`, `xChainId`, `SpokeChainId`, `MoneyMarketError`/`IntentError`/`StakingError`/`BridgeError`/`MigrationError`/`AssetServiceError`/`ConcentratedLiquidityError`/`RelayError`). Load this skill if EITHER applies; the body gates by mode.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
4
8
|
---
|
|
5
9
|
|
|
6
10
|
# When to use this skill
|
|
@@ -15,6 +19,47 @@ AGENTS.md routes you here when you're working with `@sodax/sdk` v2 — either wr
|
|
|
15
19
|
|
|
16
20
|
For React dapps using hooks → use `sodax-dapp-kit` instead (this skill is still relevant for any unwrapped SDK call).
|
|
17
21
|
|
|
22
|
+
## Prefer a granular skill if the feature is known
|
|
23
|
+
|
|
24
|
+
If the user has already picked a single feature, load the matching granular skill instead of this broad one — it loads ~3 KB of focused workflow vs this file's ~13 KB and links directly into the right knowledge files. The granular skills sit in the same family (`sdk`) and cover both integration and migration via internal cross-links.
|
|
25
|
+
|
|
26
|
+
| Feature | Granular skill | Trigger phrases |
|
|
27
|
+
|---|---|---|
|
|
28
|
+
| Intent-based swap (market + limit orders) | [`./swap/SKILL.md`](./swap/SKILL.md) | "swap with Sodax", "limit order", "cancel intent" |
|
|
29
|
+
| Cross-chain lending / borrowing | [`./money-market/SKILL.md`](./money-market/SKILL.md) | "supply", "borrow", "withdraw collateral", "repay" |
|
|
30
|
+
| Direct token bridge via vault | [`./bridge/SKILL.md`](./bridge/SKILL.md) | "bridge tokens", "cross-chain transfer" |
|
|
31
|
+
| SODA ↔ xSoda staking | [`./staking/SKILL.md`](./staking/SKILL.md) | "stake SODA", "instant unstake", "claim staking rewards" |
|
|
32
|
+
| Concentrated-liquidity LP | [`./dex/SKILL.md`](./dex/SKILL.md) | "LP position", "concentrated liquidity", "deposit hub assets" |
|
|
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
|
+
| Partner fees | [`./partner/SKILL.md`](./partner/SKILL.md) | "claim partner fee", "partner auto-swap preference", "approve partner fee token" |
|
|
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) | "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" |
|
|
38
|
+
|
|
39
|
+
Load this broad skill (keep reading below) when:
|
|
40
|
+
|
|
41
|
+
- The feature is not yet decided.
|
|
42
|
+
- The task spans **multiple** features (e.g. swap + money-market in one flow).
|
|
43
|
+
- The consumer is doing a **full v1 → v2 port** of an existing codebase.
|
|
44
|
+
|
|
45
|
+
## Out of scope
|
|
46
|
+
|
|
47
|
+
This skill documents the **SDK call sites** — what to import, how to construct `Sodax`, which method to call, and how to handle the `Result<T>`. It does **not** prescribe application-layer concerns.
|
|
48
|
+
|
|
49
|
+
### Where to go for the things this skill does NOT cover
|
|
50
|
+
|
|
51
|
+
- **Wallet provider implementations** (`IEvmWalletProvider`, `ISolanaWalletProvider`, etc.) → **load the `sodax-wallet-sdk-core` skill** (integration mode). It ships ready-made provider classes for all 9 chain families, both private-key (Node / scripts) and browser-extension modes. This skill only treats wallet providers as a contract (`declare const evmWallet: IEvmWalletProvider`).
|
|
52
|
+
- **React hooks wrapping the SDK** → **load the `sodax-dapp-kit` skill** instead of this one.
|
|
53
|
+
- **Browser wallet connectivity** (connect / disconnect / chain switching for React apps) → **load the `sodax-wallet-sdk-react` skill**.
|
|
54
|
+
|
|
55
|
+
### App-layer concerns the SDK is intentionally silent on
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
62
|
+
|
|
18
63
|
---
|
|
19
64
|
|
|
20
65
|
## Integration mode (writing new v2 code)
|
|
@@ -31,8 +76,8 @@ Follow in order. Skipping `ai-rules.md` is the most common cause of agents rever
|
|
|
31
76
|
|
|
32
77
|
1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DO NOT / workflow / stop conditions.
|
|
33
78
|
2. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — install, initialize, first-run troubleshooting.
|
|
34
|
-
3. For your feature, read [`integration/knowledge/features/`](./integration/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `
|
|
35
|
-
4. For specific patterns (init, raw vs signed, chain narrowing, gas, testing, errors), read [`integration/knowledge/recipes/`](./integration/knowledge/recipes/).
|
|
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`.
|
|
80
|
+
4. For specific patterns (init, raw vs signed, chain narrowing, gas, testing, errors, logging), read [`integration/knowledge/recipes/`](./integration/knowledge/recipes/).
|
|
36
81
|
5. Lookups (chain keys, error codes, public API surface, wallet provider types, glossary) → [`integration/knowledge/reference/`](./integration/knowledge/reference/).
|
|
37
82
|
6. Non-EVM quirks (Stellar trustline, BTC PSBT, Solana PDA, ICON, NEAR) → [`integration/knowledge/chain-specifics.md`](./integration/knowledge/chain-specifics.md).
|
|
38
83
|
|
|
@@ -44,29 +89,9 @@ Follow in order. Skipping `ai-rules.md` is the most common cause of agents rever
|
|
|
44
89
|
4. **Signed vs raw is a discriminated union.** `WalletProviderSlot<K, Raw>` enforces at compile time: `{ raw: false, walletProvider }` for signing, `{ raw: true }` for unsigned-tx building. Mixing them is a TypeScript error.
|
|
45
90
|
5. **Config is dynamic; overrides only land on `sodax.config`.** Always read via `sodax.config.*` (e.g. `sodax.config.spokeChainConfig[chainKey]`). Direct imports of `spokeChainConfig` / `sodaxConfig` from `@sodax/types` / `@sodax/sdk` are packaged-default snapshots and silently miss both `await sodax.config.initialize()` updates and `new Sodax(config)` overrides.
|
|
46
91
|
|
|
47
|
-
### Top traps
|
|
48
|
-
|
|
49
|
-
1. **Reaching for a `*SpokeProvider`.** They're deleted. Pass an object satisfying the chain-specific `I*WalletProvider` interface directly into the SDK call payload. Implementations come from your application — write your own or install `@sodax/wallet-sdk-core`.
|
|
50
|
-
2. **Forgetting `raw: false`.** Without the discriminator, `walletProvider` is rejected with "Object literal may only specify known properties." Add `raw: false` for signed flows; `raw: true` for unsigned-tx building.
|
|
51
|
-
3. **Importing from `@sodax/types` directly.** `@sodax/sdk` re-exports the entire `@sodax/types` surface. Add `@sodax/sdk` as your only dependency; importing `@sodax/types` separately risks version skew.
|
|
52
|
-
4. **Treating `Result<T>` as throw-on-failure.** v2 mutation methods do **not** throw on SDK-level failure — they resolve `{ ok: false, error }`. A `try/catch` only catches *exceptions* from inside `mutationFn` (e.g. missing `walletProvider`); it will **not** catch `RELAY_TIMEOUT` or `EXECUTION_FAILED`. Branch on `.ok`.
|
|
53
|
-
5. **Reading `xToken.xChainId` or hard-coding `*_MAINNET_CHAIN_ID`.** Renamed: `XToken.chainKey` and `ChainKeys.*`. v1 numeric/string chain-id constants are gone.
|
|
54
|
-
|
|
55
|
-
### Conventions agents must follow (integration)
|
|
92
|
+
### Top traps, conventions, verification
|
|
56
93
|
|
|
57
|
-
|
|
58
|
-
- **`(feature, code)` for error switching.** Use `isSodaxError(e)`, then `e.feature` and `e.code` for routing logic. Don't string-match on `e.message`.
|
|
59
|
-
- **`ChainKeys.*` over hard-coded strings.** The set of supported chains evolves per release.
|
|
60
|
-
- **No `as unknown as <Type>` double-casts.** v2 type narrowing makes them unnecessary — chain-key generic flow + `GetWalletProviderType<K>` resolves to the exact interface.
|
|
61
|
-
- **Don't generate `try { await sodax.<method>(...) } catch` for SDK-level failures.** That catch never fires for `Result.!ok`. Branch on `result.ok`.
|
|
62
|
-
- Import only from the package root: `import { Sodax, ChainKeys, type SpokeChainKey } from '@sodax/sdk'`. Don't deep-import from `dist/...`.
|
|
63
|
-
|
|
64
|
-
### Verification (integration)
|
|
65
|
-
|
|
66
|
-
1. `pnpm tsc --noEmit` from the consumer repo — must exit clean.
|
|
67
|
-
2. Every `await sodax.<feature>.<method>(...)` call site has `if (!result.ok)` branching.
|
|
68
|
-
3. No `xToken.xChainId`, no `*_MAINNET_CHAIN_ID`, no `*SpokeProvider` references.
|
|
69
|
-
4. `isSodaxError(e)` (not bare `instanceof SodaxError`) in cross-bundle code.
|
|
94
|
+
The DO / DO NOT / verification checklist lives in [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — read it before writing any call site. The biggest source of generated v1-style code is skipping it.
|
|
70
95
|
|
|
71
96
|
---
|
|
72
97
|
|
|
@@ -86,10 +111,10 @@ If the consumer has v1 fingerprints AND also wants new features: **do migration
|
|
|
86
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.
|
|
87
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.
|
|
88
113
|
3. **Cross-cutting first.** In order:
|
|
89
|
-
- [`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.
|
|
90
115
|
- [`breaking-changes/architecture.md`](./migration-v1-to-v2/knowledge/breaking-changes/architecture.md) — `*SpokeProvider` deletion, `ConfigService`, relay reshape.
|
|
91
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.
|
|
92
|
-
4. **Per-feature playbooks** under [`features/`](./migration-v1-to-v2/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `
|
|
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.
|
|
93
118
|
5. **Codemods + adapters** for mechanical replacement → [`recipes.md`](./migration-v1-to-v2/knowledge/recipes.md).
|
|
94
119
|
6. **Cross-check** symbols in [`reference/`](./migration-v1-to-v2/knowledge/reference/) — `deleted-exports.md`, `error-code-crosswalk.md`, `return-shapes.md`, `sodax-config.md`.
|
|
95
120
|
|
|
@@ -107,30 +132,9 @@ Apply in this order — type-level changes don't affect behavior; runtime patter
|
|
|
107
132
|
|
|
108
133
|
Then on every signed-call payload: drop `spokeProvider`, add `walletProvider`, add `raw: false` discriminator, rename `intentParams` → `params`. Plus add `srcChainKey` + `srcAddress` to every action params object (MM, staking, deposit, …).
|
|
109
134
|
|
|
110
|
-
### Top traps
|
|
111
|
-
|
|
112
|
-
1. **Reaching for a `*SpokeProvider`.** They're deleted. Pass `walletProvider` (an `I*WalletProvider` impl) directly in the call payload.
|
|
113
|
-
2. **`instanceof MoneyMarketError` (and other module error classes).** Deleted. Replace with `isSodaxError(e) && e.feature === 'moneyMarket'`.
|
|
114
|
-
3. **Destructuring cross-chain results as arrays.** v1 had `bridge()` returning a string and others returning tuples; v2 returns `TxHashPair = { srcChainTxHash, dstChainTxHash }` for **every** cross-chain mutation. Destructure as `{ srcChainTxHash, dstChainTxHash } = result.value`.
|
|
115
|
-
4. **Keeping `try/catch` to inspect v1 error codes.** v2 returns `Result<T>` — failure lives on `result.error.code`, not on a thrown error. The v2 code names changed too — see `reference/error-code-crosswalk.md`.
|
|
116
|
-
5. **Calling `getStakingInfo(hubAddress)`.** Renamed to `getStakingInfoFromSpoke(srcAddress, srcChainKey)`. `getStakingInfo` is not a public method anymore.
|
|
117
|
-
|
|
118
|
-
### DO NOT
|
|
119
|
-
|
|
120
|
-
- Grep-replace `srcChain` → `srcChainKey` blindly. The `Intent` read shape keeps `srcChain` / `dstChain` as `IntentRelayChainId` (bigint). Only **request** types changed.
|
|
121
|
-
- Assume `BalnSwapService` lock methods (`stake`, `unstake`, `claim`, `claimUnstaked`, `cancelUnstake`, `getDetailedUserLocks`) return `Result<T>`. They still throw — known carve-out. Keep `try/catch` for those specific calls.
|
|
122
|
-
- Add `@sodax/types` as a peer dependency. It's bundled into `@sodax/sdk`'s public surface.
|
|
123
|
-
|
|
124
|
-
### Verification (migration)
|
|
125
|
-
|
|
126
|
-
```bash
|
|
127
|
-
pnpm tsc --noEmit # must exit clean
|
|
128
|
-
# No leftover v1 fingerprints:
|
|
129
|
-
grep -rE '_MAINNET_CHAIN_ID\b|\bxChainId\b|\bSpokeChainId\b|\bSpokeProvider\b|hubAssets|moneyMarketSupportedTokens' src/ # empty
|
|
130
|
-
grep -rE 'MoneyMarketError|IntentError|StakingError|BridgeError|MigrationError|AssetServiceError|ConcentratedLiquidityError|RelayError' src/ # empty
|
|
131
|
-
```
|
|
135
|
+
### Top traps, DO NOT, verification
|
|
132
136
|
|
|
133
|
-
|
|
137
|
+
The full DO / DO NOT list, mode-specific pitfalls, and verification protocol live in [`migration-v1-to-v2/knowledge/ai-rules.md`](./migration-v1-to-v2/knowledge/ai-rules.md) — read it before touching any call site. Highest-leverage rule: every `await sodax.<feature>.<method>(...)` call site must have `if (!result.ok)` branching.
|
|
134
138
|
|
|
135
139
|
---
|
|
136
140
|
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-sdk-backend-api
|
|
3
|
+
description: 'Granular skill for the @sodax/sdk v2 BackendApiService — HTTP client to the SODAX backend for intent lookup, swap-tx submission, solver orderbook, money-market position/reserve reads, and (internally) config fetching. Use when the task touches a backend read or write (e.g. "submit swap tx to Sodax backend", "Sodax getIntentByHash", "fetch money market position from Sodax backend", "Sodax orderbook", "Sodax BackendApiService", "implement custom IConfigApiV1 sandbox"). Covers BOTH integration and the load-bearing v1 → v2 Result-wrapping migration. Skill links into the parent sodax-sdk knowledge tree.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Backend API (Core SDK granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for `BackendApiService` — `sodax.backendApi`. HTTP client used by every feature for backend reads; swap-tx submission is on the sibling swaps client (`sodax.api.swaps.submitTx`). **Errors:** every method emits `feature: 'backend'` with `error.context.api: 'backend'` (the HTTP-client layer — domain tags like `'moneyMarket'` belong to the on-chain services). Data/token/MM responses are validated against valibot schemas; a contract drift returns `EXTERNAL_API_ERROR` (`context.reason: 'invalid_response_shape'`). The config/relay reads (`getAllConfig` / `getSpokeChainConfig` / `getRelayChainIdMap`) are not validated.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
1. **New code or v1 → v2 port?** Note: v2's load-bearing change is `Result`-wrapping every method (v1 threw on failure).
|
|
17
|
+
2. **Which category?**
|
|
18
|
+
- **Swap-related reads:** `getOrderbook`, `getIntentByHash`, `getIntentByTxHash`, `getUserIntents`. (Swap-tx submission — `sodax.api.swaps.submitTx` / `getSubmitTxStatus` — is on the swaps API client.)
|
|
19
|
+
- **Money-market position reads:** `getMoneyMarketPosition`, `getAllMoneyMarketAssets`, `getMoneyMarketAsset`, `getMoneyMarketAssetBorrowers`, `getMoneyMarketAssetSuppliers`, `getAllMoneyMarketBorrowers`.
|
|
20
|
+
- **`IConfigApiV1` interface methods (exactly 5):** `getChains`, `getSwapTokens`, `getSwapTokensByChainId`, `getMoneyMarketTokens`, `getMoneyMarketTokensByChainId`.
|
|
21
|
+
- **Other `BackendApiService` config reads (NOT part of `IConfigApiV1`):** `getAllConfig`, `getMoneyMarketReserveAssets`, `getRelayChainIdMap`.
|
|
22
|
+
3. **Custom `IConfigApiV1` for sandbox / fixtures?** Every method must return `Promise<Result<T>>` in v2.
|
|
23
|
+
|
|
24
|
+
## Integration workflow
|
|
25
|
+
|
|
26
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
|
|
27
|
+
2. [`../integration/knowledge/features/backend-api.md`](../integration/knowledge/features/backend-api.md) — `BackendApiService` API + `sodax.api.swaps.submitTx` call shape + custom-backend pattern.
|
|
28
|
+
3. For the `sodax.api.swaps.submitTx` + `createIntent` flow → also load [`../swap/SKILL.md`](../swap/SKILL.md) or read [`../integration/knowledge/features/swap.md`](../integration/knowledge/features/swap.md) § "Backend submit-tx flow".
|
|
29
|
+
4. Errors carry `error.context.api === 'backend'` → [`../integration/knowledge/recipes/result-and-errors.md`](../integration/knowledge/recipes/result-and-errors.md) and [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
|
|
30
|
+
|
|
31
|
+
### Backend-API-specific anti-patterns
|
|
32
|
+
|
|
33
|
+
- **Passing the `RelayExtraData` object** to `sodax.api.swaps.submitTx`'s `relayData`. The field is `string` — pass `relayData.payload`.
|
|
34
|
+
- **Using a v1 numeric `srcChainId`.** `SubmitTxRequestV2` uses `srcChainKey` (the spoke chain key string).
|
|
35
|
+
- **Implementing `IConfigApiV1` with throw-on-error semantics.** v2 interface requires `Promise<Result<T>>` — every method.
|
|
36
|
+
- **Reading money-market position from `MoneyMarketService`.** Those reads live here on `BackendApiService`.
|
|
37
|
+
|
|
38
|
+
## Migration workflow (v1 → v2)
|
|
39
|
+
|
|
40
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
|
|
41
|
+
2. [`../migration-v1-to-v2/knowledge/features/backend-api.md`](../migration-v1-to-v2/knowledge/features/backend-api.md) — the load-bearing change: every method now returns `Promise<Result<T>>`. Includes the `submitSwapTx` request-shape changes (`srcChainId` → `srcChainKey`, `relayData` object → string) and the `IConfigApiV1` sandbox-impl change.
|
|
42
|
+
3. Cross-cutting `IConfigApiV1` Result-wrapping note → [`../migration-v1-to-v2/knowledge/breaking-changes/type-system.md`](../migration-v1-to-v2/knowledge/breaking-changes/type-system.md) § 6.
|
|
43
|
+
|
|
44
|
+
## Verification
|
|
45
|
+
|
|
46
|
+
1. `pnpm tsc --noEmit` clean.
|
|
47
|
+
2. Every `await sodax.backendApi.<method>(...)` has `if (!result.ok)`.
|
|
48
|
+
3. `SubmitTxRequestV2` uses `srcChainKey` and `relayData: relayData.payload` (string).
|
|
49
|
+
4. Any custom `IConfigApiV1` implementation returns `Promise<Result<T>>` from every method.
|
|
50
|
+
|
|
51
|
+
## Related granular skills (same family)
|
|
52
|
+
|
|
53
|
+
- [`../swap/SKILL.md`](../swap/SKILL.md) — `sodax.api.swaps.submitTx` is the backend half of the step-by-step swap flow.
|
|
54
|
+
- [`../swaps-api/SKILL.md`](../swaps-api/SKILL.md) — the full typed Swaps API v2 client (`sodax.api.swaps`): quote, create-intent, submit-tx, fees, status.
|
|
55
|
+
- [`../money-market/SKILL.md`](../money-market/SKILL.md) — `BackendApiService` is the canonical source of MM position reads.
|
|
56
|
+
- [`../partner/SKILL.md`](../partner/SKILL.md), [`../recovery/SKILL.md`](../recovery/SKILL.md) — diagnostics for failures via intent / tx lookups.
|
|
57
|
+
|
|
58
|
+
For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-sdk-bridge
|
|
3
|
+
description: 'Granular skill for the @sodax/sdk v2 bridge feature only — cross-chain token transfer via vault. Use when the task is specifically bridging (e.g. "bridge tokens cross-chain with Sodax", "Sodax bridge", "transfer USDC from Arbitrum to Stellar via Sodax", "check bridgeable amount"). The bridge() method returns `TxHashPair = { srcChainTxHash, dstChainTxHash }` for every cross-chain mutation. Covers BOTH integration (new v2 code) and migration (port v1 BridgeService). Skill links into the parent sodax-sdk knowledge tree. For React dapps, prefer sodax-dapp-kit.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Bridge (Core SDK granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for `BridgeService` — `sodax.bridge`. Feature tag: `'bridge'`.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
1. **New code or v1 → v2 port?**
|
|
17
|
+
2. **Signed flow (frontend) or unsigned-tx (backend)?**
|
|
18
|
+
3. **Need a bridgeable-amount precheck?** Vault deposit limits may cap the transfer; `getBridgeableAmount` (or equivalent) read tells you the cap before submitting.
|
|
19
|
+
4. **Source / destination chains** — confirm both are supported spoke chains, and the destination address format matches the chain (vd Stellar address starts with `G`, Solana base58, Bitcoin specific encodings).
|
|
20
|
+
|
|
21
|
+
## Integration workflow
|
|
22
|
+
|
|
23
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
|
|
24
|
+
2. [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md) — API surface, `TxHashPair` return shape, bridgeable-amount reads.
|
|
25
|
+
3. Path-specific recipe:
|
|
26
|
+
- Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
|
|
27
|
+
- Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
|
|
28
|
+
4. Destination-chain quirks (Stellar trustline, BTC PSBT, Solana PDA) → [`../integration/knowledge/chain-specifics.md`](../integration/knowledge/chain-specifics.md).
|
|
29
|
+
5. Errors (`feature: 'bridge'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
|
|
30
|
+
|
|
31
|
+
### Bridge-specific anti-patterns
|
|
32
|
+
|
|
33
|
+
- **Destructuring the return as an array or single hash.** v2 ALWAYS returns `{ srcChainTxHash, dstChainTxHash }` for cross-chain mutations — destructure by name.
|
|
34
|
+
- **Skipping the bridgeable-amount check.** Submitting an amount over the vault cap returns `EXECUTION_FAILED`; cheaper to check first.
|
|
35
|
+
|
|
36
|
+
## Migration workflow (v1 → v2)
|
|
37
|
+
|
|
38
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
|
|
39
|
+
2. [`../migration-v1-to-v2/knowledge/features/bridge.md`](../migration-v1-to-v2/knowledge/features/bridge.md) — v1 `bridge()` returned a string; v2 returns `TxHashPair`. Update all destructuring sites.
|
|
40
|
+
3. v1 `BridgeError` → v2 `SodaxError<C>` with `feature: 'bridge'`.
|
|
41
|
+
|
|
42
|
+
## Verification
|
|
43
|
+
|
|
44
|
+
1. `pnpm tsc --noEmit` clean.
|
|
45
|
+
2. Every `await sodax.bridge.<method>(...)` has `if (!result.ok)`.
|
|
46
|
+
3. No string-typed return destructuring at `bridge()` call sites.
|
|
47
|
+
|
|
48
|
+
## Related granular skills (same family)
|
|
49
|
+
|
|
50
|
+
- [`../swap/SKILL.md`](../swap/SKILL.md) — for intent-based cross-chain swaps (different from a direct bridge: swap goes via a solver).
|
|
51
|
+
- [`../recovery/SKILL.md`](../recovery/SKILL.md) — `RecoveryService` for stuck assets on the hub.
|
|
52
|
+
|
|
53
|
+
For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
|