@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.
Files changed (168) hide show
  1. package/.claude-plugin/plugin.json +1 -0
  2. package/AGENTS.md +123 -13
  3. package/README.md +5 -2
  4. package/package.json +1 -1
  5. package/skills/sodax-build/SKILL.md +90 -0
  6. package/skills/sodax-build/knowledge/README.md +35 -0
  7. package/skills/sodax-build/knowledge/brief-template.md +41 -0
  8. package/skills/sodax-build/knowledge/chains-and-assets.md +26 -0
  9. package/skills/sodax-build/knowledge/example-sessions.md +84 -0
  10. package/skills/sodax-build/knowledge/feature-catalog.md +51 -0
  11. package/skills/sodax-build/knowledge/glossary.md +35 -0
  12. package/skills/sodax-build/knowledge/handoff.md +60 -0
  13. package/skills/sodax-build/knowledge/interview-guide.md +66 -0
  14. package/skills/sodax-build/knowledge/monetization.md +37 -0
  15. package/skills/sodax-build/knowledge/use-case-gallery.md +32 -0
  16. package/skills/sodax-dapp-kit/SKILL.md +6 -2
  17. package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +65 -0
  18. package/skills/sodax-dapp-kit/bitcoin/SKILL.md +57 -0
  19. package/skills/sodax-dapp-kit/bridge/SKILL.md +59 -0
  20. package/skills/sodax-dapp-kit/dex/SKILL.md +60 -0
  21. package/skills/sodax-dapp-kit/integration/knowledge/README.md +1 -1
  22. package/skills/sodax-dapp-kit/integration/knowledge/features/README.md +3 -2
  23. package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +71 -11
  24. package/skills/sodax-dapp-kit/integration/knowledge/features/bitcoin.md +10 -6
  25. package/skills/sodax-dapp-kit/integration/knowledge/features/dex.md +2 -2
  26. package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +112 -0
  27. package/skills/sodax-dapp-kit/integration/knowledge/features/migration.md +1 -1
  28. package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +6 -1
  29. package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
  30. package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
  31. package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
  32. package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
  33. package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md +8 -8
  34. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +168 -0
  35. package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
  36. package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +4 -4
  37. package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
  38. package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md +3 -0
  39. package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md +1 -1
  40. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +67 -6
  41. package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +49 -0
  42. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +54 -0
  43. package/skills/sodax-dapp-kit/migration/SKILL.md +64 -0
  44. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md +1 -1
  45. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +2 -2
  46. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md +1 -1
  47. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md +1 -1
  48. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +19 -10
  49. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md +2 -2
  50. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
  51. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
  52. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/migration.md +1 -1
  53. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +3 -3
  54. package/skills/sodax-dapp-kit/money-market/SKILL.md +61 -0
  55. package/skills/sodax-dapp-kit/staking/SKILL.md +60 -0
  56. package/skills/sodax-dapp-kit/swap/SKILL.md +64 -0
  57. package/skills/sodax-sdk/SKILL.md +54 -50
  58. package/skills/sodax-sdk/backend-api/SKILL.md +58 -0
  59. package/skills/sodax-sdk/bridge/SKILL.md +53 -0
  60. package/skills/sodax-sdk/dex/SKILL.md +54 -0
  61. package/skills/sodax-sdk/integration/knowledge/README.md +5 -3
  62. package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
  63. package/skills/sodax-sdk/integration/knowledge/architecture.md +26 -39
  64. package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
  65. package/skills/sodax-sdk/integration/knowledge/features/README.md +6 -3
  66. package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +92 -0
  67. package/skills/sodax-sdk/integration/knowledge/features/bridge.md +48 -11
  68. package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
  69. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +175 -0
  70. package/skills/sodax-sdk/integration/knowledge/features/{icx-bnusd-baln.md → migration.md} +75 -30
  71. package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
  72. package/skills/sodax-sdk/integration/knowledge/features/partner.md +86 -0
  73. package/skills/sodax-sdk/integration/knowledge/features/recovery.md +51 -0
  74. package/skills/sodax-sdk/integration/knowledge/features/staking.md +8 -3
  75. package/skills/sodax-sdk/integration/knowledge/features/swap.md +106 -22
  76. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
  77. package/skills/sodax-sdk/integration/knowledge/quickstart.md +1 -1
  78. package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -0
  79. package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
  80. package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
  81. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +34 -2
  82. package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +102 -0
  83. package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +28 -4
  84. package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
  85. package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
  86. package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
  87. package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +40 -4
  88. package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +32 -9
  89. package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
  90. package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -4
  91. package/skills/sodax-sdk/leverage-yield/SKILL.md +50 -0
  92. package/skills/sodax-sdk/migration/SKILL.md +69 -0
  93. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
  94. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +6 -10
  95. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
  96. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +3 -3
  97. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -5
  98. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +2 -2
  99. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/README.md +4 -2
  100. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +92 -0
  101. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
  102. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
  103. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/{icx-bnusd-baln.md → migration.md} +31 -29
  104. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
  105. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +64 -0
  106. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +35 -0
  107. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +8 -3
  108. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
  109. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +19 -17
  110. package/skills/sodax-sdk/money-market/SKILL.md +56 -0
  111. package/skills/sodax-sdk/partner/SKILL.md +55 -0
  112. package/skills/sodax-sdk/recovery/SKILL.md +53 -0
  113. package/skills/sodax-sdk/staking/SKILL.md +53 -0
  114. package/skills/sodax-sdk/swap/SKILL.md +72 -0
  115. package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
  116. package/skills/sodax-wallet-sdk-core/SKILL.md +7 -3
  117. package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +54 -0
  118. package/skills/sodax-wallet-sdk-core/evm/SKILL.md +54 -0
  119. package/skills/sodax-wallet-sdk-core/icon/SKILL.md +54 -0
  120. package/skills/sodax-wallet-sdk-core/injective/SKILL.md +54 -0
  121. package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
  122. package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +2 -2
  123. package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
  124. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
  125. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
  126. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
  127. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
  128. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
  129. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
  130. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
  131. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
  132. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
  133. package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
  134. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
  135. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
  136. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/testing.md +1 -1
  137. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
  138. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
  139. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
  140. package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
  141. package/skills/sodax-wallet-sdk-core/near/SKILL.md +54 -0
  142. package/skills/sodax-wallet-sdk-core/solana/SKILL.md +54 -0
  143. package/skills/sodax-wallet-sdk-core/stacks/SKILL.md +53 -0
  144. package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +54 -0
  145. package/skills/sodax-wallet-sdk-core/sui/SKILL.md +53 -0
  146. package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
  147. package/skills/sodax-wallet-sdk-react/bridge-to-sdk/SKILL.md +56 -0
  148. package/skills/sodax-wallet-sdk-react/connect/SKILL.md +59 -0
  149. package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
  150. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
  151. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
  152. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +10 -10
  153. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
  154. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +4 -4
  155. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
  156. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
  157. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
  158. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
  159. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
  160. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
  161. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/ssr-setup.md +24 -19
  162. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +1 -1
  163. package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +51 -0
  164. package/skills/sodax-wallet-sdk-react/switch-chain/SKILL.md +51 -0
  165. package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +54 -0
  166. package/skills/sodax-wallet-sdk-react/walletconnect/SKILL.md +52 -0
  167. package/skills/sodax-sdk/integration/knowledge/features/auxiliary-services.md +0 -189
  168. 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 } = useBackendSubmitSwapTx();
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({ rawTx, walletProvider });
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
- - const { data: hasTrustline } = useStellarTrustlineCheck(account, asset);
87
- + const { data: hasTrustline } = useStellarTrustlineCheck({ params: { account, asset } });
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
- - const request = useRequestTrustline(walletProvider);
90
- - await request.mutateAsync({ account, asset });
91
- + const { mutateAsync: request } = useRequestTrustline();
92
- + await request({ account, asset, walletProvider });
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: { spokeChainKey, srcAddress } });
108
+ + const { data: hubAddress } = useDeriveUserWalletAddress({ params: { spokeChainId, spokeAddress } });
100
109
  ```
101
110
 
102
111
  ## Pitfalls
@@ -1,8 +1,8 @@
1
- # Bitcoin (Radfi) migration — v1 → v2 (dapp-kit)
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 / Radfi 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.
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` field renamed to `dstAddress`** for consistency with the rest of the SDK.
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. Their inputs use `srcChainKey` (not `srcChainId`); the result is spread into the mutation's `params` field at the call site.
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/icx-bnusd-baln.md` — underlying SDK migration migration.
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 with `{ token, amount, chainId, walletProvider }` under `params`. |
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` | Mutation. `apiConfig` moved from hook init to `mutate(vars)`. |
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/Radfi mutations | Standard pattern — drop hook-init args; pass through `mutate(vars)`. |
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: 'INTEGRATION (write NEW v2 code) — @sodax/sdk v2 is the SODAX cross-chain DeFi SDK (hub-and-spoke architecture, Sonic hub + 19 spoke chains across EVM and non-EVM). Covers intent-based swaps, lending/borrowing (money market), staking, bridging, concentrated-liquidity DEX, ICX/bnUSD/BALN 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.'
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`, `icx-bnusd-baln.md`, `auxiliary-services.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 to avoid (integration)
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
- - **`Result<T>` discrimination on `.ok`.** Always branch on `result.ok` before reading `.value` or `.error`. Forward sub-Results without re-wrapping (`if (!sub.ok) return sub`).
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`, `IConfigApi` Result.
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`, `icx-bnusd-baln.md`, `auxiliary-services.md` — read only the ones the consumer uses.
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 to avoid (migration)
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
- Every `await sodax.<feature>.<method>(...)` call site must have `if (!result.ok)` branching (highest-leverage change — if you stop early, ensure result branching is at least in place).
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).