@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
@@ -1,189 +0,0 @@
1
- # Auxiliary services — `PartnerService`, `RecoveryService`, `BackendApiService`
2
-
3
- Three small services grouped together. None has the surface area of the major features (swap, money market, etc.), but they're load-bearing in real consumer flows.
4
-
5
- ## `PartnerService` — `sodax.partners`
6
-
7
- Partner-fee handling. `PartnerService` itself only exposes `feeClaim: PartnerFeeClaimService` and `config: ConfigService` as public fields. Every operation lives on `sodax.partners.feeClaim`.
8
-
9
- **Feature tag for errors:** `'partner'`.
10
-
11
- ### Methods (all on `sodax.partners.feeClaim`)
12
-
13
- ```ts
14
- // Token approval
15
- sodax.partners.feeClaim.isTokenApproved({ token, srcAddress }): Promise<Result<boolean, Error>>;
16
- sodax.partners.feeClaim.approveToken<Raw>(args): Promise<Result<TxReturnType, Error>>;
17
-
18
- // Auto-swap preferences (whether partner-collected fees auto-swap into a target asset)
19
- sodax.partners.feeClaim.getAutoSwapPreferences(queryAddress): Promise<Result<AutoSwapPreferences, Error>>;
20
- sodax.partners.feeClaim.setSwapPreference<K, Raw>(args): Promise<Result<TxReturnType, Error>>;
21
-
22
- // Fee claim flows
23
- sodax.partners.feeClaim.swap(args): Promise<Result<...>>; // immediate fee swap
24
- sodax.partners.feeClaim.createIntentAutoSwap<Raw>(args): Promise<Result<...>>; // intent-driven auto-swap
25
-
26
- // Reads
27
- sodax.partners.feeClaim.fetchAssetsBalances(args): Promise<Result<...>>;
28
- sodax.partners.feeClaim.getOriginalAssetAddress(chainId, hubAsset): OriginalAssetAddress | undefined;
29
- sodax.partners.feeClaim.getSpokeTokenFromOriginalAssetAddress(...): /* … */;
30
- ```
31
-
32
- ### Common call shape
33
-
34
- ```ts
35
- // 1. Check whether the partner's fee token is approved on the hub:
36
- const approved = await sodax.partners.feeClaim.isTokenApproved({
37
- token: '0x…', // hub asset address
38
- srcAddress: partnerAddress,
39
- });
40
-
41
- // 2. Approve once if not:
42
- if (approved.ok && !approved.value) {
43
- await sodax.partners.feeClaim.approveToken({
44
- params: { token: '0x…', amount: 2n ** 256n - 1n },
45
- raw: false,
46
- walletProvider: sonicWp,
47
- });
48
- }
49
-
50
- // 3. Configure auto-swap preference (one-time):
51
- await sodax.partners.feeClaim.setSwapPreference({
52
- params: { /* preference fields */ },
53
- raw: false,
54
- walletProvider: sonicWp,
55
- });
56
- ```
57
-
58
- ### Error codes
59
-
60
- `feature: 'partner'`. Action methods get the full exec set; reads get `LookupErrorCode` partitioned by `error.context.method`.
61
-
62
- ---
63
-
64
- ## `RecoveryService` — `sodax.recovery`
65
-
66
- Withdraw stuck assets from a user's hub wallet abstraction back to a spoke chain. Useful when a cross-chain operation deposited to the hub but the destination step failed (e.g. relay timeout after the spoke tx landed).
67
-
68
- **Feature tag for errors:** `'recovery'`.
69
-
70
- ### Methods
71
-
72
- ```ts
73
- // Read: list balances of all known hub assets in a user's hub wallet abstraction.
74
- sodax.recovery.fetchHubAssetBalances(args): Promise<Result<HubAssetBalance[], SodaxError>>;
75
-
76
- // Mutation: withdraw a single hub asset back to a spoke chain.
77
- // Returns a tx-pair when raw: false (the hub-side spend + the relayed spoke-side receive).
78
- sodax.recovery.withdrawHubAsset<K extends SpokeChainKey, Raw extends boolean>(
79
- action: WithdrawHubAssetAction<K, Raw>,
80
- ): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
81
- ```
82
-
83
- ### Common call shape
84
-
85
- ```ts
86
- // 1. Find what's stuck on the hub for this user:
87
- const balances = await sodax.recovery.fetchHubAssetBalances({ /* user / hub-wallet args */ });
88
- if (!balances.ok || balances.value.length === 0) return;
89
-
90
- // 2. Withdraw one entry back to a spoke chain:
91
- const result = await sodax.recovery.withdrawHubAsset({
92
- params: {
93
- /* hub-asset address, amount, destination spoke chain key, destination address */
94
- },
95
- raw: false,
96
- walletProvider: sonicWp,
97
- });
98
- ```
99
-
100
- ### Error codes
101
-
102
- `feature: 'recovery'`. The mutation method returns the full exec set (including relay codes); the read method returns `LookupErrorCode` partitioned by `error.context.method`.
103
-
104
- ### When to use
105
-
106
- Recovery is a workaround for failed cross-chain operations. Best used **after** investigating why the original operation failed — relay timeouts may resolve on retry; structural failures need fixing first.
107
-
108
- ---
109
-
110
- ## `BackendApiService` — `sodax.backendApi`
111
-
112
- HTTP client for backend services. Provides intent lookup, swap-tx submission, solver orderbook queries, money-market position/reserve reads, and (internally) config fetching. Most consumer-side code uses just `submitSwapTx`, `getIntentByHash` / `getIntentByTxHash`, and the money-market read methods.
113
-
114
- **Feature tag for errors:** appears under multiple features depending on the call site (`'swap'` for `submitSwapTx`); errors carry `error.context.api: 'backend'`.
115
-
116
- ### Methods
117
-
118
- ```ts
119
- // Swap-related
120
- sodax.backendApi.submitSwapTx(request, config?): Promise<Result<SubmitSwapTxResponse>>;
121
- sodax.backendApi.getSubmitSwapTxStatus(...): Promise<Result<...>>;
122
- sodax.backendApi.getOrderbook(...): Promise<Result<OrderbookEntry[]>>;
123
- sodax.backendApi.getIntentByHash(intentHash, config?): Promise<Result<IntentResponse>>;
124
- sodax.backendApi.getIntentByTxHash(txHash, config?): Promise<Result<IntentResponse>>;
125
- sodax.backendApi.getUserIntents(...): Promise<Result<IntentResponse[]>>;
126
-
127
- // Money-market reads (these are the canonical reads for MM positions/reserves;
128
- // MoneyMarketService does NOT expose getReservesData / getUserReservesData / etc.)
129
- sodax.backendApi.getMoneyMarketPosition(...): Promise<Result<...>>;
130
- sodax.backendApi.getAllMoneyMarketAssets(config?): Promise<Result<MoneyMarketAsset[]>>;
131
- sodax.backendApi.getMoneyMarketAsset(reserveAddress, config?): Promise<Result<MoneyMarketAsset>>;
132
- sodax.backendApi.getMoneyMarketAssetBorrowers(...): Promise<Result<...>>;
133
- sodax.backendApi.getMoneyMarketAssetSuppliers(...): Promise<Result<...>>;
134
- sodax.backendApi.getAllMoneyMarketBorrowers(...): Promise<Result<...>>;
135
-
136
- // Config-API methods (used internally by ConfigService — implements `IConfigApi`)
137
- sodax.backendApi.getAllConfig(config?): Promise<Result<GetAllConfigApiResponse>>;
138
- sodax.backendApi.getChains(config?): Promise<Result<GetChainsApiResponse>>;
139
- sodax.backendApi.getSwapTokens(config?): Promise<Result<GetSwapTokensApiResponse>>;
140
- sodax.backendApi.getSwapTokensByChainId(...): Promise<Result<XToken[]>>;
141
- sodax.backendApi.getMoneyMarketTokens(config?): Promise<Result<GetMoneyMarketTokensApiResponse>>;
142
- sodax.backendApi.getMoneyMarketReserveAssets(...): Promise<Result<...>>;
143
- sodax.backendApi.getMoneyMarketTokensByChainId(...): Promise<Result<XToken[]>>;
144
- sodax.backendApi.getRelayChainIdMap(config?): Promise<Result<GetRelayChainIdMapApiResponse>>;
145
- ```
146
-
147
- All methods return `Result<T, SodaxError>` where the error carries `feature: 'swap' | …` (depending on call site) and `error.context.api === 'backend'`.
148
-
149
- ### Common call shape — `submitSwapTx`
150
-
151
- After `sodax.swaps.createIntent({ params, raw: false, walletProvider })` returns:
152
-
153
- ```ts
154
- const submitResult = await sodax.backendApi.submitSwapTx({
155
- txHash: spokeTxHash as string,
156
- srcChainKey: src.chain,
157
- walletAddress: '0x…',
158
- intent: swapIntentData,
159
- relayData: relayData.payload, // string, not the RelayExtraData object
160
- });
161
-
162
- if (!submitResult.ok) return;
163
- ```
164
-
165
- ### Custom backend (sandbox / fixtures)
166
-
167
- Inject an `IConfigApi` implementation via `SodaxConfig.backendApi.api`:
168
-
169
- ```ts
170
- const sandboxApi: IConfigApi = {
171
- async getChains() { return { ok: true, value: [/* fixture */] }; },
172
- // …
173
- };
174
-
175
- const sodax = new Sodax({
176
- backendApi: { url: 'unused', api: sandboxApi },
177
- });
178
- await sodax.config.initialize();
179
- ```
180
-
181
- Every method on `IConfigApi` returns `Promise<Result<T>>` in v2.
182
-
183
- ---
184
-
185
- ## Cross-references
186
-
187
- - v1 → v2 migration of these auxiliary services: [`features/auxiliary-services.md`](../../../migration-v1-to-v2/knowledge/features/auxiliary-services.md).
188
- - The full `submitSwapTx` flow with `createIntent` upstream: [`./swap.md`](swap.md) § "Backend submit-tx flow".
189
- - Error model context fields (`error.context.api`, `error.context.method`): [`../reference/`](../reference/) § 3.
@@ -1,156 +0,0 @@
1
- # Auxiliary services migration — v1 → v2
2
-
3
- Pure-SDK migration playbook for `PartnerService`, `RecoveryService`, and `BackendApiService`. Three small services grouped because each has a small surface area.
4
-
5
- Pair: [`features/auxiliary-services.md`](../../../integration/knowledge/features/auxiliary-services.md).
6
-
7
- ## TL;DR
8
-
9
- 1. **`PartnerService`:** standard pattern. Drop `spokeProvider`; pass `walletProvider`. Add `srcChainKey` + `srcAddress` to claim params. v1's 5 typed errors collapse into `SodaxError<C>` with `feature: 'partner'`.
10
- 2. **`RecoveryService`:** **new in v2.** No v1 equivalent — there's no migration to do for code that didn't exist before. Just integration: see [`features/auxiliary-services.md`](../../../integration/knowledge/features/auxiliary-services.md).
11
- 3. **`BackendApiService`:** the load-bearing change. **Every method now returns `Promise<Result<T>>`** (v1 returned plain `Promise<T>` and threw on failure). `IConfigApi` implementations must update method signatures.
12
- 4. **`SubmitSwapTxRequest.srcChainId` → `srcChainKey`.** And `relayData` field is `string` (`relayData.payload`), not the `RelayExtraData` object. (Cross-cutting detail; covered in detail in [`swap.md`](swap.md).)
13
-
14
- ## `PartnerService`
15
-
16
- ### Type / symbol cheat sheet
17
-
18
- | Type | v1 shape | v2 shape | Notes |
19
- |---|---|---|---|
20
- | Partner action params | non-generic | now generic `<K>` with `srcChainKey`, `srcAddress` | |
21
- | Partner errors (5 types) | `PartnerFeeClaimError<...>` and 4 siblings | `SodaxError<C>` with `feature: 'partner'` | All 5 v1 typed errors collapse. |
22
-
23
- ### v1 → v2 error code crosswalk
24
-
25
- All 5 v1 partner error codes map to `EXECUTION_FAILED` with `error.context.action` discriminating between the operations.
26
-
27
- ### Per-method delta
28
-
29
- Partner operations live on `sodax.partners.feeClaim` (a `PartnerFeeClaimService`), not directly on `sodax.partners`. v1 method names also changed:
30
-
31
- ```diff
32
- - await sodax.partners.claimFees({ /* … */ }, spokeProvider);
33
- + // Approve once, then configure auto-swap preference, then run swaps.
34
- + // Full method list lives in integration/features/auxiliary-services.md.
35
- + const approved = await sodax.partners.feeClaim.isTokenApproved({ token, srcAddress });
36
- + if (approved.ok && !approved.value) {
37
- + await sodax.partners.feeClaim.approveToken({
38
- + params: { token, amount },
39
- + raw: false,
40
- + walletProvider,
41
- + });
42
- + }
43
- ```
44
-
45
- ### Pitfalls
46
-
47
- 1. **Partner methods moved.** They live on `sodax.partners.feeClaim`, not `sodax.partners` directly. The parent only exposes `feeClaim` and `config` as public fields.
48
- 2. **All 5 v1 partner errors collapse to `feature: 'partner'`.** Even though they share the `EXECUTION_FAILED` code with every other feature.
49
-
50
- ---
51
-
52
- ## `RecoveryService`
53
-
54
- **No v1 equivalent.** v1 didn't have a public recovery service. Failed cross-chain operations had to be handled ad-hoc.
55
-
56
- If you have v1 code that worked around this (e.g. manually walked the hub wallet abstraction to find stuck assets), replace it with `fetchHubAssetBalances` + `withdrawHubAsset`:
57
-
58
- ```ts
59
- const balances = await sodax.recovery.fetchHubAssetBalances({ /* user / hub-wallet args */ });
60
- if (balances.ok && balances.value.length > 0) {
61
- await sodax.recovery.withdrawHubAsset({
62
- params: { /* hub-asset address, amount, destination spoke chain + address */ },
63
- raw: false,
64
- walletProvider: sonicWp,
65
- });
66
- }
67
- ```
68
-
69
- See [`features/auxiliary-services.md`](../../../integration/knowledge/features/auxiliary-services.md) § "RecoveryService".
70
-
71
- ---
72
-
73
- ## `BackendApiService`
74
-
75
- The load-bearing v1 → v2 change here is **`Result`-wrapping every method**.
76
-
77
- ### Type / symbol cheat sheet
78
-
79
- | Method | v1 return | v2 return |
80
- |---|---|---|
81
- | `submitSwapTx` | `Promise<SubmitSwapTxResponse>` | `Promise<Result<SubmitSwapTxResponse>>` |
82
- | `getIntentByHash` | `Promise<IntentResponse>` | `Promise<Result<IntentResponse>>` |
83
- | `getIntentByTxHash` | (n/a in v1) | `Promise<Result<IntentResponse>>` (v2-new) |
84
- | `getOrderbook` (was `getSolverOrderbook`) | `Promise<OrderbookEntry[]>` | `Promise<Result<OrderbookEntry[]>>` |
85
- | `getUserIntents` (was `getUserSwapHistory`) | `Promise<IntentResponse[]>` | `Promise<Result<IntentResponse[]>>` |
86
- | `getChains` | `Promise<ChainConfig[]>` | `Promise<Result<GetChainsApiResponse>>` |
87
- | `getSwapTokens` | `Promise<SwapTokenConfig>` | `Promise<Result<GetSwapTokensApiResponse>>` |
88
- | `getSwapTokensByChainId` | `Promise<XToken[]>` | `Promise<Result<XToken[]>>` |
89
- | `getMoneyMarketTokens` | `Promise<MMTokenConfig>` | `Promise<Result<GetMoneyMarketTokensApiResponse>>` |
90
- | `getMoneyMarketTokensByChainId` | `Promise<XToken[]>` | `Promise<Result<XToken[]>>` |
91
- | `SubmitSwapTxRequest.srcChainId` | numeric chain id | renamed → `srcChainKey: SpokeChainKey` |
92
- | `SubmitSwapTxRequest.relayData` | `RelayExtraData` object | now `string` (use `relayData.payload`) |
93
-
94
- ### Per-method delta
95
-
96
- ```diff
97
- - const response: SubmitSwapTxResponse = await sodax.backendApi.submitSwapTx(request);
98
- - // throws on failure
99
- + const result = await sodax.backendApi.submitSwapTx({
100
- + txHash: spokeTxHash as string,
101
- + srcChainKey: src.chain, // was: srcChainId
102
- + walletAddress: '0x…',
103
- + intent: swapIntentData,
104
- + relayData: relayData.payload, // was: relayData (object)
105
- + });
106
- + if (!result.ok) {
107
- + // result.error: SodaxError with feature: 'swap', context.api: 'backend'
108
- + return;
109
- + }
110
- + const response = result.value;
111
- ```
112
-
113
- ### Custom `IConfigApi` (sandbox / test fixtures)
114
-
115
- If you implemented `IConfigApi` for a sandbox or test fixture:
116
-
117
- ```diff
118
- const sandboxApi: IConfigApi = {
119
- - async getChains(): Promise<ChainConfig[]> {
120
- - return [/* fixture */];
121
- - },
122
- - async getSwapTokens(): Promise<SwapTokenConfig> { /* … */ },
123
- + async getChains(): Promise<Result<ChainConfig[], unknown>> {
124
- + return { ok: true, value: [/* fixture */] };
125
- + },
126
- + async getSwapTokens(): Promise<Result<SwapTokenConfig, unknown>> { /* … */ },
127
- // …5 methods total
128
- };
129
- ```
130
-
131
- Every method on the contract returns `Promise<Result<T>>` in v2.
132
-
133
- ### Pitfalls
134
-
135
- 1. **`SubmitSwapTxRequest.relayData` is `string`, not the `RelayExtraData` object.** v1 took the object; v2 takes the `payload` field as a string.
136
- 2. **Backend errors carry `error.context.api === 'backend'`** but the `feature` reflects the call site (`'swap'` for `submitSwapTx`, `'moneyMarket'` for MM-related backend calls, etc.). Use both for logger tag pairs.
137
- 3. **Custom `IConfigApi` implementations must return `Result<T>`** — old throw-on-error implementations will compile-error against the v2 interface.
138
-
139
- ---
140
-
141
- ## Verification
142
-
143
- ```bash
144
- pnpm -C <your-app-dir> checkTs
145
-
146
- # Targeted scans:
147
- grep -rE "spokeProvider:\s*\w+|isPartnerError\b|PartnerFeeClaimError\b" src/
148
- grep -rE "srcChainId:\s*\w+|\.relayData(?!\s*\.payload)" src/ # legacy field name + non-string relayData
149
- ```
150
-
151
- ## Cross-references
152
-
153
- - v2 auxiliary services usage: [`features/auxiliary-services.md`](../../../integration/knowledge/features/auxiliary-services.md).
154
- - `submitSwapTx` flow with `createIntent` upstream: [`./swap.md`](swap.md) (the swap migration covers the request-shape changes in detail).
155
- - Result/error model: [`../breaking-changes/result-and-errors.md`](../breaking-changes/result-and-errors.md).
156
- - `IConfigApi` Result-wrapping cross-cutting note: [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 6.