@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
@@ -16,7 +16,9 @@ DO / DO NOT / workflow / stop conditions for AI agents porting v1 `@sodax/sdk` c
16
16
  3. **Apply changes in order: type-level first, runtime second.** Type-level renames don't affect behavior; runtime patterns (Result branching, error model) require thinking. Doing them in the wrong order means the typecheck stays noisy and you can't see the real problems.
17
17
  4. **Re-run `pnpm tsc --noEmit` after every step.** Each step should reduce the error count. If errors grow, you've introduced something — back out and try again.
18
18
 
19
- ## DO
19
+ > **v2 cross-cutting rules apply too.** Everything in [`integration/ai-rules.md`](../../integration/knowledge/ai-rules.md) (Result branching, `isSodaxError`, `TxHashPair`, `BalnSwapService` throws, package-root imports, no `@sodax/types` peer dep, …) holds when writing migrated code. The DO / DO NOT below are **migration-specific** rules on top.
20
+
21
+ ## DO (migration-specific)
20
22
 
21
23
  - **DO** start with mechanical type renames:
22
24
  - `*_MAINNET_CHAIN_ID` → `ChainKeys.*` (regex: `(\w+)_MAINNET_CHAIN_ID` → `ChainKeys.$1_MAINNET`).
@@ -28,18 +30,12 @@ DO / DO NOT / workflow / stop conditions for AI agents porting v1 `@sodax/sdk` c
28
30
  - **DO** add the `raw: false` (or `raw: true`) discriminator to every signed call shape that previously took `{ intentParams, spokeProvider }`. Also rename `intentParams` → `params` and drop `spokeProvider` in favor of `walletProvider`.
29
31
  - **DO** convert v1 `try/catch` to `result.ok` branching last — touching every call site is the biggest commit, easiest to do once the type-level changes settled.
30
32
  - **DO** treat the `Result<T>` ↔ `try/catch` migration as the *highest-leverage* change. If you stop early, ensure result branching is at least in place even if the surrounding error UX is rough.
31
- - **DO** use `isSodaxError(e)` over bare `instanceof SodaxError` in the new error-handling branches. `instanceof` is fragile across bundle copies.
32
- - **DO** branch on `(error.feature, error.code)` for fine-grained UX. The narrow per-method code unions enable exhaustive `switch`.
33
33
 
34
- ## DO NOT
34
+ ## DO NOT (migration-specific)
35
35
 
36
- - **DO NOT** grep-replace `srcChain` → `srcChainKey` blindly. The `Intent` *read* shape (returned from `createIntent` / `getIntentByHash` / etc.) keeps `srcChain` and `dstChain` as `IntentRelayChainId` (bigint) — those did **not** rename. Only **request** types changed (`CreateIntentParams`, `CreateLimitOrderParams`, `SubmitSwapTxRequest`).
36
+ - **DO NOT** grep-replace `srcChain` → `srcChainKey` blindly. The `Intent` *read* shape (returned from `createIntent` / `getIntentByHash` / etc.) keeps `srcChain` and `dstChain` as `IntentRelayChainId` (bigint) — those did **not** rename. Only **request** types changed (`CreateIntentParams`, `CreateLimitOrderParams`, `SubmitTxRequestV2`).
37
37
  - **DO NOT** treat `instanceof MoneyMarketError` (or any other module-error class) as still working. Those classes are deleted. Replace with `isSodaxError(e) && e.feature === 'moneyMarket'`.
38
- - **DO NOT** destructure cross-chain mutation results as arrays. v1 had `bridge()` returning a string and others returning tuples; v2 returns `TxHashPair = { srcChainTxHash, dstChainTxHash }` for **every** cross-chain mutation (bridge, staking, dex, MM, migration). Destructure as `{ srcChainTxHash, dstChainTxHash } = result.value`.
39
- - **DO NOT** assume `BalnSwapService` lock-management methods (`stake`, `unstake`, `claim`, `claimUnstaked`, `cancelUnstake`, `getDetailedUserLocks`) return `Result<T>`. They still throw — known carve-out. Keep `try/catch` for those specific calls.
40
- - **DO NOT** keep `try/catch` blocks expecting them to catch SDK-level failures from non-Baln methods. v2 mutation methods resolve `{ ok: false, error }` rather than throwing — `catch` only fires for synchronous wrapper exceptions (e.g. missing `walletProvider`).
41
- - **DO NOT** call `getStakingInfo(hubAddress)` in v2. It's `getStakingInfoFromSpoke(srcAddress, srcChainKey)` now. `getStakingInfo` is not a public method.
42
- - **DO NOT** import `@sodax/types` as a peer dependency. It's bundled into `@sodax/sdk`'s public surface; declaring it separately invites version skew.
38
+ - **DO NOT** pass v1 spoke-side state into `getStakingInfo(hubAddress)`. The method is still public in v2 but expects a *hub* address. v1 call sites that used `spokeProvider`-derived data should switch to `getStakingInfoFromSpoke(srcAddress, srcChainKey)` which derives the hub wallet internally.
43
39
  - **DO NOT** keep `try { await sodax.swaps.createIntent(...) } catch` and expect to inspect `e.code === 'CREATE_INTENT_FAILED'`. The v2 code is `INTENT_CREATION_FAILED` and lives on `result.error.code` (Result branch), not on a thrown error. See [`reference/error-code-crosswalk.md`](reference/error-code-crosswalk.md) for the full v1 → v2 code crosswalk.
44
40
 
45
41
  ## Stop conditions (defer to user)
@@ -175,8 +175,8 @@ If you pass a config override to `new Sodax({ ... })`, put solver endpoints in `
175
175
 
176
176
  v1 had per-feature relay helpers (each feature module had its own `*WaitForRelay()` or `relay*Tx()` function). v2 centralises this into `IntentRelayApiService` with two public entry points:
177
177
 
178
- - `submitTransaction({ srcChainKey, txHash, payload })` — POSTs the spoke transaction to the relay submit endpoint and resolves the relay's first-stage acknowledgement.
179
- - `relayTxAndWaitPacket({ srcChainKey, dstChainKey, txHash, payload, timeout? })` — runs `submitTransaction` and then polls until the destination packet reaches `executed`. Resolves with `{ srcTxHash, dstTxHash, packet }` on success.
178
+ - `submitTransaction(payload, apiUrl)` — TWO positional args (`payload: IntentRelayRequest<'submit'>`, `apiUrl: HttpUrl`), not an options object. POSTs the spoke transaction to the relay submit endpoint and resolves the relay's first-stage acknowledgement.
179
+ - `relayTxAndWaitPacket({ srcTxHash, data, chainKey, relayerApiEndpoint, timeout, pollTxHash? })` — `RelayAndWaitParams`: `data` is the whole `RelayExtraData` / `OnDemandRelayData` object, `chainKey` is the source `SpokeChainKey`. Runs `submitTransaction` and then polls until the destination packet reaches `executed`. Resolves with `{ srcTxHash, dstTxHash, packet }` on success.
180
180
 
181
181
  Internally, every feature service now calls `relayTxAndWaitPacket` for the spoke→hub leg. Failures from this layer surface to consumers via `mapRelayFailure`.
182
182
 
@@ -45,7 +45,7 @@ The **complete list** of services whose public methods return `Result<T>`:
45
45
  - `RecoveryService`
46
46
  - `BackendApiService`
47
47
  - `SpokeService` (router-level helpers)
48
- - `IConfigApi` implementations (every method)
48
+ - `IConfigApiV1` implementations (every method)
49
49
 
50
50
  Private helpers may still throw; the outer `try/catch` at each public method's boundary absorbs those and converts them to `{ ok: false, error }`.
51
51
 
@@ -126,7 +126,7 @@ A `try { await sodax.<method>(...) } catch` block in v2 only catches **exception
126
126
  ```ts
127
127
  class SodaxError<C extends SodaxErrorCode = SodaxErrorCode> extends Error {
128
128
  readonly code: C; // closed 13-code reason union
129
- readonly feature: SodaxFeature; // 'swap' | 'moneyMarket' | 'bridge' | 'staking' | 'migration' | 'dex' | 'partner' | 'recovery'
129
+ readonly feature: SodaxFeature; // 'swap' | 'moneyMarket' | 'bridge' | 'staking' | 'migration' | 'dex' | 'partner' | 'recovery' | 'backend' | 'leverageYield'
130
130
  readonly cause?: unknown;
131
131
  readonly context?: SodaxErrorContext;
132
132
 
@@ -216,7 +216,7 @@ Every public method declares a `<MethodName>ErrorCode` narrow union built via `E
216
216
  ```ts
217
217
  type CreateSupplyIntentErrorCode = Extract<
218
218
  SodaxErrorCode,
219
- 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN'
219
+ 'USER_REJECTED' | 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN'
220
220
  >;
221
221
 
222
222
  // In the queryFn or call site:
@@ -11,7 +11,7 @@ Every type-level rename and shape change introduced by v2. Fix these first — o
11
11
  3. [Wallet-provider typing](#3-wallet-provider-typing) — `GetWalletProviderType<K>` and `WalletProviderSlot<K, Raw>` replace ad-hoc spoke-provider classes.
12
12
  4. [`Token` / `XToken` field renames](#4-token--xtoken-field-renames) — `xChainId` → `chainKey`; `Token` → `XToken`.
13
13
  5. [`RpcConfig` reshape](#5-rpcconfig-reshape) — now keyed by `ChainKey` values; chain-family-specific shapes for Bitcoin and Stellar.
14
- 6. [`IConfigApi` Result-wrapping](#6-iconfigapi-result-wrapping) — every method returns `Promise<Result<T>>`.
14
+ 6. [`IConfigApiV1` Result-wrapping](#6-iconfigapiv1-result-wrapping) — every method returns `Promise<Result<T>>`.
15
15
  7. [Address-type rename](#7-address-type-rename) — `AddressType` → `BtcAddressType`.
16
16
  8. [Wallet-provider `chainType` discriminant](#8-wallet-provider-chaintype-discriminant) — every `I*WalletProvider` declares a literal field.
17
17
  9. [`ChainId` / `SpokeChainId` → `SpokeChainKey`](#9-chainid--spokechainid--spokechainkey) — type alias rename.
@@ -47,6 +47,7 @@ v1 exported one constant per chain (`SONIC_MAINNET_CHAIN_ID`, `ARBITRUM_MAINNET_
47
47
  | `BASE_MAINNET_CHAIN_ID` | `ChainKeys.BASE_MAINNET` | `'0x2105.base'` |
48
48
  | `BSC_MAINNET_CHAIN_ID` | `ChainKeys.BSC_MAINNET` | `'0x38.bsc'` |
49
49
  | `ETHEREUM_MAINNET_CHAIN_ID` | `ChainKeys.ETHEREUM_MAINNET` | `'ethereum'` |
50
+ | `HEDERA_MAINNET_CHAIN_ID` | `ChainKeys.HEDERA_MAINNET` | `'hedera'` |
50
51
  | `HYPEREVM_MAINNET_CHAIN_ID` | `ChainKeys.HYPEREVM_MAINNET` | `'hyper'` |
51
52
  | `ICON_MAINNET_CHAIN_ID` | `ChainKeys.ICON_MAINNET` | `'0x1.icon'` |
52
53
  | `INJECTIVE_MAINNET_CHAIN_ID` | `ChainKeys.INJECTIVE_MAINNET` | `'injective-1'` |
@@ -192,7 +193,7 @@ v1 consumers reached into a global `hubAssets[chainId][address]` map to get the
192
193
 
193
194
  ### Pitfall
194
195
 
195
- Read shapes like `Intent` and `IntentResponse` from the backend keep `srcChain` / `dstChain` as the **relay** chain id (numeric, `IntentRelayChainId`). They are **not** chain keys and were **not** renamed to `srcChainKey`/`dstChainKey`. Only **request** types (`CreateIntentParams`, `CreateLimitOrderParams`, `SubmitSwapTxRequest`) gained the `*ChainKey` field names.
196
+ Read shapes like `Intent` and `IntentResponse` from the backend keep `srcChain` / `dstChain` as the **relay** chain id (numeric, `IntentRelayChainId`). They are **not** chain keys and were **not** renamed to `srcChainKey`/`dstChainKey`. Only **request** types (`CreateIntentParams`, `CreateLimitOrderParams`, `SubmitTxRequestV2`) gained the `*ChainKey` field names.
196
197
 
197
198
  ### Exception — partner module read shapes DID rename
198
199
 
@@ -244,9 +245,9 @@ Bitcoin and Stellar have richer RPC needs than other chains (multiple endpoints,
244
245
 
245
246
  ---
246
247
 
247
- ## 6. `IConfigApi` Result-wrapping
248
+ ## 6. `IConfigApiV1` Result-wrapping
248
249
 
249
- Every method on the `IConfigApi` contract changed signature in v2. v1 returned plain `Promise<T>` and threw on failure; v2 returns `Promise<Result<T>>` and never throws.
250
+ Every method on the `IConfigApiV1` contract changed signature in v2. v1 returned plain `Promise<T>` and threw on failure; v2 returns `Promise<Result<T>>` and never throws.
250
251
 
251
252
  | Method | v1 return | v2 return |
252
253
  |---|---|---|
@@ -257,7 +258,7 @@ Every method on the `IConfigApi` contract changed signature in v2. v1 returned p
257
258
  | `getMoneyMarketTokensByChainId` | `Promise<XToken[]>` | `Promise<Result<XToken[]>>` |
258
259
  | `getRelayChainIdMap` | (n/a in v1) | `Promise<Result<GetRelayChainIdMapApiResponse>>` (v2-new) |
259
260
 
260
- If you implemented a custom `IConfigApi` (e.g. for a sandbox or test fixture), update every method signature. If you only consumed the default implementation through `Sodax.config`, the SDK already uses `Result` internally — your consumer-side code doesn't see the wrapping.
261
+ If you implemented a custom `IConfigApiV1` (e.g. for a sandbox or test fixture), update every method signature. If you only consumed the default implementation through `Sodax.config`, the SDK already uses `Result` internally — your consumer-side code doesn't see the wrapping.
261
262
 
262
263
  ---
263
264
 
@@ -46,7 +46,7 @@ Work this top-down. Each step is independent enough to land as its own commit; t
46
46
  the v2 shape is { tx, intent, relayData }. Stop destructuring tx-pair
47
47
  results as arrays — every cross-chain mutation returns
48
48
  TxHashPair = { srcChainTxHash, dstChainTxHash }.
49
- [ ] 15. For every backend-API call site: every method on IConfigApi now returns
49
+ [ ] 15. For every backend-API call site: every method on IConfigApiV1 now returns
50
50
  Promise<Result<T>>. Wrap or unwrap accordingly.
51
51
  [ ] 16. (Optional) Adopt isSodaxError(e) over instanceof SodaxError in cross-bundle
52
52
  / cross-realm contexts.
@@ -63,5 +63,5 @@ After items 1–17 land, the typecheck should be clean. The remaining work is pe
63
63
  - Items 5–6, 11–12: [`breaking-changes/architecture.md`](breaking-changes/architecture.md).
64
64
  - Items 7–8, 13: [`breaking-changes/architecture.md`](breaking-changes/architecture.md) § "WalletProviderSlot" + per-feature files.
65
65
  - Items 9–10, 14, 16: [`breaking-changes/result-and-errors.md`](breaking-changes/result-and-errors.md).
66
- - Item 15: [`features/auxiliary-services.md`](features/auxiliary-services.md) § "BackendApiService".
66
+ - Item 15: [`features/backend-api.md`](features/backend-api.md).
67
67
  - Item 17 + the long tail: [`features/`](features/), one per feature you use.
@@ -9,8 +9,10 @@ One file per feature, paired with the v2 design counterpart in [`features/`](../
9
9
  | Staking | [`staking.md`](staking.md) |
10
10
  | Bridge | [`bridge.md`](bridge.md) |
11
11
  | DEX | [`dex.md`](dex.md) |
12
- | ICX/bnUSD/BALN | [`icx-bnusd-baln.md`](icx-bnusd-baln.md) |
13
- | Auxiliary services | [`auxiliary-services.md`](auxiliary-services.md) — `PartnerService` + `RecoveryService` + `BackendApiService`. The backend-API one is the load-bearing change: every method now returns `Promise<Result<T>>`. |
12
+ | ICX/bnUSD/BALN | [`migration.md`](migration.md) |
13
+ | Partner | [`partner.md`](partner.md) — standard pattern; 5 v1 typed errors collapse into `SodaxError<C>` with `feature: 'partner'`. |
14
+ | Recovery | [`recovery.md`](recovery.md) — new in v2; no v1 equivalent. |
15
+ | Backend API | [`backend-api.md`](backend-api.md) — load-bearing change: every method now returns `Promise<Result<T>>`. |
14
16
 
15
17
  ## Reading order within a feature
16
18
 
@@ -0,0 +1,92 @@
1
+ # Backend API migration — v1 → v2
2
+
3
+ Pure-SDK migration playbook for `BackendApiService`. The load-bearing v1 → v2 change here is **`Result`-wrapping every method**.
4
+
5
+ Pair: [`features/backend-api.md`](../../../integration/knowledge/features/backend-api.md).
6
+
7
+ ## TL;DR
8
+
9
+ 1. **Every method now returns `Promise<Result<T>>`** (v1 returned plain `Promise<T>` and threw on failure). `IConfigApiV1` implementations must update method signatures.
10
+ 2. **Swap-tx submission moved off `BackendApiService` onto the swaps API client** — `sodax.backendApi.submitSwapTx` is now `sodax.api.swaps.submitTx` (request `SubmitTxRequestV2`, response `SubmitTxResponseV2`). The request renamed `srcChainId` → `srcChainKey`, and `relayData` is a `string` (`relayData.payload`), not the `RelayExtraData` object. (Cross-cutting detail; covered in detail in [`swap.md`](swap.md).)
11
+
12
+ ## Type / symbol cheat sheet
13
+
14
+ | Method | v1 return | v2 return |
15
+ |---|---|---|
16
+ | `submitSwapTx` → `sodax.api.swaps.submitTx` | `Promise<SubmitSwapTxResponse>` | `Promise<Result<SubmitTxResponseV2>>` |
17
+ | `getIntentByHash` | `Promise<IntentResponse>` | `Promise<Result<IntentResponse>>` |
18
+ | `getIntentByTxHash` | (n/a in v1) | `Promise<Result<IntentResponse>>` (v2-new) |
19
+ | `getOrderbook` (was `getSolverOrderbook`) | `Promise<OrderbookResponse>` | `Promise<Result<OrderbookResponse>>` (object `{ total, data: Array<{ intentState, intentData }> }`, not an array) |
20
+ | `getUserIntents` (was `getUserSwapHistory`) | `Promise<UserIntentsResponse>` | `Promise<Result<UserIntentsResponse>>` (`{ total, offset, limit, items: IntentResponse[] }` — intents under `.items`) |
21
+ | `getChains` | `Promise<ChainConfig[]>` | `Promise<Result<GetChainsApiResponse>>` |
22
+ | `getSwapTokens` | `Promise<SwapTokenConfig>` | `Promise<Result<GetSwapTokensApiResponse>>` |
23
+ | `getSwapTokensByChainId` | `Promise<XToken[]>` | `Promise<Result<XToken[]>>` |
24
+ | `getMoneyMarketTokens` | `Promise<MMTokenConfig>` | `Promise<Result<GetMoneyMarketTokensApiResponse>>` |
25
+ | `getMoneyMarketTokensByChainId` | `Promise<XToken[]>` | `Promise<Result<XToken[]>>` |
26
+ | `srcChainId` → `srcChainKey` (`SubmitTxRequestV2`) | numeric chain id | `srcChainKey` (spoke chain key string) |
27
+ | `relayData` (`SubmitTxRequestV2`) | `RelayExtraData` object | now `string` (use `relayData.payload`) |
28
+
29
+ ## Per-method delta
30
+
31
+ ```diff
32
+ - const response: SubmitSwapTxResponse = await sodax.backendApi.submitSwapTx(request);
33
+ - // throws on failure
34
+ + const result = await sodax.api.swaps.submitTx({ // moved off BackendApiService
35
+ + txHash: spokeTxHash as string,
36
+ + srcChainKey: src.chain, // was: srcChainId
37
+ + walletAddress: '0x…',
38
+ + intent, // IntentRequestV2 (was: SwapIntentData)
39
+ + relayData: relayData.payload, // was: relayData (object)
40
+ + });
41
+ + if (!result.ok) {
42
+ + // result.error: SodaxError with feature: 'backend', context.api: 'swaps'
43
+ + return;
44
+ + }
45
+ + const response = result.value; // SubmitTxResponseV2
46
+ ```
47
+
48
+ ## Custom `IConfigApiV1` (sandbox / test fixtures)
49
+
50
+ If you implemented `IConfigApiV1` for a sandbox or test fixture, two things changed in v2:
51
+
52
+ **1. Method signatures.** Every method now returns `Promise<Result<T>>` instead of throwing on failure:
53
+
54
+ ```diff
55
+ const sandboxApi: IConfigApiV1 = {
56
+ - async getChains(): Promise<ChainConfig[]> {
57
+ - return [/* fixture */];
58
+ - },
59
+ - async getSwapTokens(): Promise<SwapTokenConfig> { /* … */ },
60
+ + async getChains(): Promise<Result<readonly SpokeChainKey[]>> {
61
+ + return { ok: true, value: [/* fixture: chain KEYS, not configs */] };
62
+ + },
63
+ + async getSwapTokens(): Promise<Result<Record<SpokeChainKey, readonly XToken[]>>> { /* … */ },
64
+ // …5 methods total
65
+ };
66
+ ```
67
+
68
+ **2. Injection mechanism.** `SodaxConfig` does NOT expose a typed slot to inject a custom `IConfigApiV1` at construction. v1 patterns that passed a custom api into `new Sodax(...)` no longer typecheck. Point at a local mock via `SodaxConfig.api.baseURL`, or inject your own `BackendApiService`-compatible mock at the app layer. See [`../../../integration/knowledge/architecture.md`](../../../integration/knowledge/architecture.md) § 4 "Custom backend" for the v2 pattern.
69
+
70
+ ## Pitfalls
71
+
72
+ 1. **`SubmitTxRequestV2.relayData` is `string`, not the `RelayExtraData` object.** v1 took the object; v2 takes the `payload` field as a string.
73
+ 2. **Backend + swaps-API errors both carry `feature: 'backend'`** with `context.endpoint`, but the `error.context.api` differs by client: `'backend'` for `BackendApiService` reads, `'swaps'` for `SwapsApiService` (`sodax.api.swaps`) calls. The domain feature tags (`'swap'`, `'moneyMarket'`, …) come from the on-chain feature services, not the HTTP clients. Use `(feature, context.api)` for logger tag pairs.
74
+ 3. **Custom `IConfigApiV1` implementations must return `Result<T>`** — old throw-on-error implementations will compile-error against the v2 interface.
75
+
76
+ ## Verification
77
+
78
+ ```bash
79
+ pnpm -C <your-app-dir> checkTs
80
+
81
+ # Targeted scans:
82
+ grep -rE "srcChainId:\s*\w+|\.relayData(?!\s*\.payload)" src/ # legacy field name + non-string relayData
83
+ ```
84
+
85
+ ## Cross-references
86
+
87
+ - v2 backend API usage: [`features/backend-api.md`](../../../integration/knowledge/features/backend-api.md).
88
+ - submit-tx flow with `createIntent` upstream: [`./swap.md`](swap.md) (the swap migration covers the request-shape changes in detail).
89
+ - Partner migration (separate service): [`./partner.md`](partner.md).
90
+ - Recovery migration (separate service, new in v2): [`./recovery.md`](recovery.md).
91
+ - Result/error model: [`../breaking-changes/result-and-errors.md`](../breaking-changes/result-and-errors.md).
92
+ - `IConfigApiV1` Result-wrapping cross-cutting note: [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 6.
@@ -7,9 +7,9 @@ Pair: [`features/bridge.md`](../../../integration/knowledge/features/bridge.md).
7
7
  ## TL;DR
8
8
 
9
9
  1. **Drop `spokeProvider`. Pass `walletProvider` directly.**
10
- 2. **Add `srcChainKey` + `srcAddress` to `CreateBridgeParams<K>`.** Generic added.
10
+ 2. **Add `srcChainKey` + `srcAddress` to `CreateBridgeIntentParams<K>`.** Generic added.
11
11
  3. **`bridge()` returns `Result<TxHashPair>`.** v1 returned a single `string` tx hash; v2 returns `{ srcChainTxHash, dstChainTxHash }` (the spoke + hub tx hashes) wrapped in `Result`.
12
- 4. **`createBridgeIntent()` is spoke-only — no relay.** Same shape as the swap `createIntent`: returns `{ tx, intent, relayData }` for the spoke transaction. Useful when you need manual relay control.
12
+ 4. **`createBridgeIntent()` is spoke-only — no relay.** Same shape as the swap `createIntent`: returns `IntentTxResult<K, Raw> = { tx, relayData }` for the spoke transaction. Useful when you need manual relay control.
13
13
  5. **Read methods reshaped.** `getBridgeableAmount` returns `Promise<Result<BridgeLimit>>` (was `Promise<bigint>`) and now takes two `XToken` objects. `getBridgeableTokens` is synchronous (was async) and takes `(from, to, token)`.
14
14
  6. **Errors → `SodaxError` + `Result<T>`.** v1's `BridgeError<BridgeErrorCode>` is gone.
15
15
 
@@ -72,7 +72,7 @@ Pair: [`features/bridge.md`](../../../integration/knowledge/features/bridge.md).
72
72
  - await sodax.bridge.createBridgeIntent({ params, spokeProvider });
73
73
  + const result = await sodax.bridge.createBridgeIntent({ params, raw: false, walletProvider });
74
74
  + if (!result.ok) return;
75
- + const { tx, intent, relayData } = result.value;
75
+ + const { tx, relayData } = result.value;
76
76
  + // Submit relayData.payload via your custom relay if needed.
77
77
  ```
78
78
 
@@ -92,13 +92,13 @@ Standard pattern:
92
92
 
93
93
  ```ts
94
94
  await sodax.bridge.approve({
95
- params: { srcChainKey, srcAddress, srcAsset, amount },
95
+ params: { srcChainKey, srcAddress, srcToken, amount },
96
96
  raw: false,
97
97
  walletProvider,
98
98
  });
99
99
 
100
100
  const allowed = await sodax.bridge.isAllowanceValid({
101
- params: { srcChainKey, srcAddress, srcAsset, amount },
101
+ params: { srcChainKey, srcAddress, srcToken, amount },
102
102
  raw: true, // read-only
103
103
  });
104
104
  ```
@@ -66,14 +66,12 @@ Pair: [`features/dex.md`](../../../integration/knowledge/features/dex.md).
66
66
 
67
67
  ### `supplyLiquidity` (mint new) and `increaseLiquidity` (existing)
68
68
 
69
- The pure-helper `createSupplyLiquidityParamsProps` returns the helper-relevant subset (no `srcChainKey`/`srcAddress`). Spread it at the call site:
69
+ An `@sodax/sdk` consumer builds the `ClSupplyParams` object directly — there is no SDK-side params helper. (The `createSupplyLiquidityParamsProps` convenience helper lives only in `@sodax/dapp-kit`; don't import it from `@sodax/sdk`.) Construct the object inline and add `srcChainKey`/`srcAddress`:
70
70
 
71
71
  ```diff
72
- - const params = createSupplyLiquidityParamsProps({ /* … */ });
73
72
  - await sodax.dex.clService.supplyLiquidity({ params, spokeProvider });
74
- + const helperOutput = createSupplyLiquidityParamsProps({ /* … */ });
75
73
  + const srcAddress = (await walletProvider.getWalletAddress()) as `0x${string}`;
76
- + const params = { ...helperOutput, srcChainKey, srcAddress };
74
+ + const params = { srcChainKey, srcAddress, poolKey, tickLower, tickUpper, liquidity, amount0Max, amount1Max, sqrtPriceX96 };
77
75
  + const result = await sodax.dex.clService.supplyLiquidity({ params, raw: false, walletProvider });
78
76
  + if (!result.ok) return;
79
77
  + const { dstChainTxHash } = result.value;
@@ -2,14 +2,14 @@
2
2
 
3
3
  Pure-SDK migration playbook for `MigrationService` (the SDK module — not v1→v2 SDK porting).
4
4
 
5
- Pair: [`features/icx-bnusd-baln.md`](../../../integration/knowledge/features/icx-bnusd-baln.md).
5
+ Pair: [`features/migration.md`](../../../integration/knowledge/features/migration.md).
6
6
 
7
7
  ## TL;DR
8
8
 
9
9
  1. **Drop `spokeProvider`. Pass `walletProvider` directly.**
10
- 2. **Add `srcChainKey` + `srcAddress` to every action params.** All migration param types (`MigrationParams<K>`, `UnifiedBnUSDMigrateParams<K>`, `IcxToSodaMigrateParams<K>`, `RevertSodaToIcxParams<K>`, `BalnSwapParams<K>`) gained both fields and a `<K>` generic.
10
+ 2. **Add `srcChainKey` + `srcAddress` to every action params.** The concrete migration param types are `IcxMigrateParams`, `UnifiedBnUSDMigrateParams<K>`, `IcxCreateRevertMigrationParams`, and `BalnMigrateParams`. Only `UnifiedBnUSDMigrateParams` is generic over `<K>`; the ICX and BALN types are **non-generic**. `MigrationParams<K>` is a **union** of these concrete types, not a base record.
11
11
  3. **All 4 orchestrator methods return `Result<TxHashPair>`.** v1 returned a string tx hash and threw on error.
12
- 4. **`migratebnUSD` carries `direction` on error context** — `'forward'` (legacy → new) or `'reverse'` (new → legacy). The SDK detects direction from `(srcToken, dstToken)` addresses.
12
+ 4. **`migratebnUSD` carries `direction` on error context** — `'forward'` (legacy → new) or `'reverse'` (new → legacy). The SDK detects direction from `(srcbnUSD, dstbnUSD)` addresses.
13
13
  5. **`BalnSwapService` lock-management methods STILL THROW.** `claim`, `claimUnstaked`, `stake`, `unstake`, `cancelUnstake`, `getDetailedUserLocks` — these 6 methods preserve the v1 throw-on-error contract. Wrap in `try/catch` until a future cleanup release converts them to `Result`.
14
14
  6. **Errors → `SodaxError` + `Result<T>`.** v1's `MigrationError<MigrationErrorCode>` is gone.
15
15
 
@@ -19,9 +19,9 @@ Pair: [`features/icx-bnusd-baln.md`](../../../integration/knowledge/features/icx
19
19
 
20
20
  | Type | v1 shape | v2 shape | Notes |
21
21
  |---|---|---|---|
22
- | `MigrationParams` | non-generic | `MigrationParams<K extends SpokeChainKey>` with `srcChainKey`, `srcAddress`, `amount`, `dstAddress?` | Generic added. |
23
- | `UnifiedBnUSDMigrateParams` | non-generic | `UnifiedBnUSDMigrateParams<K>` extends `MigrationParams<K>` with `srcToken`, `dstToken` | Generic added. |
24
- | `BalnSwapParams` | `{ amount, lockPeriodMonths }` | `MigrationParams<K> & { lockPeriodMonths }` | Adds chain context. |
22
+ | `MigrationParams` | non-generic | `MigrationParams<K extends SpokeChainKey>` = union of `IcxMigrateParams \| UnifiedBnUSDMigrateParams<K> \| BalnMigrateParams` | Now a **union** of the concrete param types, not a base record. |
23
+ | `UnifiedBnUSDMigrateParams` | non-generic | `UnifiedBnUSDMigrateParams<K>` with `srcChainKey`, `srcAddress`, `srcbnUSD`, `dstChainKey`, `dstbnUSD`, `amount`, `dstAddress` (bnUSD fields typed `string`) | Generic added; bnUSD fields are `srcbnUSD`/`dstbnUSD`, and `dstChainKey` is required. |
24
+ | `BalnMigrateParams` (was `BalnSwapParams`) | `{ amount, lockPeriodMonths }` | `{ srcChainKey, srcAddress, amount, lockupPeriod: LockupPeriod, dstAddress, stake }` (**non-generic**) | Renamed; `lockupPeriod` is a `LockupPeriod` enum (seconds), `stake: boolean` required. |
25
25
 
26
26
  ### Deleted symbols
27
27
 
@@ -50,12 +50,13 @@ Pair: [`features/icx-bnusd-baln.md`](../../../integration/knowledge/features/icx
50
50
  - await sodax.migration.migrateBnUSDForward({ amount, /* … */ }, spokeProvider);
51
51
  - await sodax.migration.migrateBnUSDReverse({ amount, /* … */ }, spokeProvider);
52
52
 
53
- + // v2 has one method; SDK detects direction from (srcToken, dstToken):
53
+ + // v2 has one method; SDK detects direction from (srcbnUSD, dstbnUSD):
54
54
  + const result = await sodax.migration.migratebnUSD({
55
55
  + params: {
56
56
  + srcChainKey, srcAddress,
57
- + srcToken, // legacy or new bnUSD
58
- + dstToken, // the other one
57
+ + srcbnUSD, // legacy or new bnUSD
58
+ + dstChainKey, // required
59
+ + dstbnUSD, // the other one
59
60
  + amount,
60
61
  + dstAddress,
61
62
  + },
@@ -83,24 +84,24 @@ Standard pattern:
83
84
  + const { srcChainTxHash, dstChainTxHash } = result.value;
84
85
  ```
85
86
 
86
- `migrateBaln` adds `lockPeriodMonths: 0 | 1 | 2 | 3 | 6 | 12 | 18 | 24` to the params. Reward multiplier ranges 0.5x (0 months) – 1.5x (24 months).
87
+ `migrateBaln` adds `lockupPeriod: LockupPeriod` (a `LockupPeriod` enum measured in **seconds**: `NO_LOCKUP` / `SIX_MONTHS` / `TWELVE_MONTHS` / `EIGHTEEN_MONTHS` / `TWENTY_FOUR_MONTHS` → 0/6/12/18/24 months) plus a required `stake: boolean` to the params. Reward multiplier ranges 0.5x (`NO_LOCKUP`) – 1.5x (`TWENTY_FOUR_MONTHS`).
87
88
 
88
89
  ### Approve / allowance — action-discriminated
89
90
 
91
+ `action` is the **second positional argument**, typed `MigrationAction = 'migrate' | 'revert'` — not a field inside `params`:
92
+
90
93
  ```ts
91
- await sodax.migration.approve({
92
- params: { srcChainKey, srcAddress, amount, action: 'migrateBaln' /* or migratebnUSD | migrateIcxToSoda | revertMigrateSodaToIcx */ },
93
- raw: false,
94
- walletProvider,
95
- });
96
-
97
- const allowed = await sodax.migration.isAllowanceValid({
98
- params: { srcChainKey, srcAddress, amount, action: 'migrateBaln' },
99
- raw: true, // read-only
100
- });
94
+ // approve: action-wrapped params, then the action arg
95
+ await sodax.migration.approve(
96
+ { params, raw: false, walletProvider },
97
+ 'migrate', // or 'revert'
98
+ );
99
+
100
+ // isAllowanceValid: BARE migration params (no wrapper, NOT Raw-generic, no `raw` flag) + action arg
101
+ const allowed = await sodax.migration.isAllowanceValid(params, 'migrate');
101
102
  ```
102
103
 
103
- ### `getAvailableAmount` (claimable from partial migration)
104
+ ### `getAvailableAmount` (total available SODA liquidity in the migration contract)
104
105
 
105
106
  ```diff
106
107
  - const amount: bigint = await sodax.migration.icx.getAvailableAmount(spokeProvider);
@@ -114,11 +115,12 @@ const allowed = await sodax.migration.isAllowanceValid({
114
115
  ```diff
115
116
  try {
116
117
  - const tx = await sodax.migration.balnSwapService.stake({ amount, lockPeriod }, spokeProvider);
117
- + const tx = await sodax.migration.balnSwapService.stake({
118
- + params: { srcChainKey, srcAddress, amount, lockPeriodMonths },
119
- + raw: false,
120
- + walletProvider,
121
- + });
118
+ + // stake(user, params, walletProviderSlot) — positional args, not an action wrapper:
119
+ + const tx = await sodax.migration.balnSwapService.stake(
120
+ + userAddress, // Address of the lock owner on the Sonic hub
121
+ + { lockId }, // BalnLockParams
122
+ + walletProviderSlot,
123
+ + );
122
124
  /* … */
123
125
  } catch (e) {
124
126
  /* still v1-style: catch the throw */
@@ -131,9 +133,9 @@ const allowed = await sodax.migration.isAllowanceValid({
131
133
 
132
134
  Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstChain renames, etc.) live in [`../ai-rules.md`](../ai-rules.md). The list below is feature-specific — typecheck fingerprints, return-shape diffs, and gotchas unique to this feature.
133
135
 
134
- 1. **`migratebnUSD` direction detection.** v1 had explicit forward/reverse methods; v2 detects from `(srcToken, dstToken)`. If both are on the same side (both legacy or both new), the SDK rejects with `VALIDATION_FAILED`. Use the `direction` field on `error.context` to disambiguate in error messaging.
136
+ 1. **`migratebnUSD` direction detection.** v1 had explicit forward/reverse methods; v2 detects from `(srcbnUSD, dstbnUSD)`. If both are on the same side (both legacy or both new), the SDK rejects with `VALIDATION_FAILED`. Use the `direction` field on `error.context` to disambiguate in error messaging.
135
137
  2. **BALN lock methods don't return `Result`.** Be careful migrating wrappers — if your wrapper assumes Result-shape, lock methods will produce `undefined.ok` runtime errors. Keep the `try/catch` shape.
136
- 3. **`lockPeriodMonths` is a literal union, not arbitrary `number`.** TypeScript rejects `lockPeriodMonths: 7`. Allowed values: `0 | 1 | 2 | 3 | 6 | 12 | 18 | 24`.
138
+ 3. **`lockupPeriod` is a `LockupPeriod` enum (in seconds), not a numeric months union.** Pass enum members, not raw numbers: `LockupPeriod.NO_LOCKUP` / `SIX_MONTHS` / `TWELVE_MONTHS` / `EIGHTEEN_MONTHS` / `TWENTY_FOUR_MONTHS` (mapping to 0/6/12/18/24 months — there are no 1/2/3-month options). `BalnMigrateParams` also requires `stake: boolean`.
137
139
  4. **`getAvailableAmount` lives on the sub-service `sodax.migration.icxMigration` and takes no arguments.** v1 expected `(spokeProvider)`; v2 reads on-chain SODA liquidity directly from the hub provider, so the method needs no chain context. Sub-service field names: `sodax.migration.icxMigration`, `sodax.migration.bnUSDMigrationService`, `sodax.migration.balnSwapService`.
138
140
  5. **`destinationExecution` phase on bnUSD errors** — these errors land **after** the relay succeeds. The spoke and hub txs may already exist; the destination-side finalization is what failed. Distinguish from primary relay errors (`phase: 'relay'`) when surfacing UX.
139
141
 
@@ -147,5 +149,5 @@ grep -rE "spokeProvider:\s*\w+|migrateBnUSDForward\b|migrateBnUSDReverse\b|isMig
147
149
 
148
150
  ## Cross-references
149
151
 
150
- - v2 token migration usage: [`features/icx-bnusd-baln.md`](../../../integration/knowledge/features/icx-bnusd-baln.md).
152
+ - v2 token migration usage: [`features/migration.md`](../../../integration/knowledge/features/migration.md).
151
153
  - Cross-cutting prerequisites listed in [`../README.md`](../README.md).
@@ -12,7 +12,7 @@ Pair: [`features/money-market.md`](../../../integration/knowledge/features/money
12
12
  4. **`MoneyMarketSupplyParams` etc. are now generic** (`MoneyMarketSupplyParams<K extends SpokeChainKey>`). Add a chain-key generic to your params variables, or let TS infer from a literal `srcChainKey`.
13
13
  5. **Replace `moneyMarketSupportedTokens[chainId]` with `sodax.moneyMarket.getSupportedTokensByChainId(chainKey)`.**
14
14
  6. **Replace `hubAssets[chainId][address]?.vault` with `token.vault`** (now baked into `XToken`). Same for `token.hubAsset`.
15
- 7. **`sodax.moneyMarket.getAToken(...)` returns `Erc20Token & { chainKey }`, not a full `XToken`.** No `hubAsset` / `vault` on the result — look up the full `XToken` via `sodax.config.getMoneyMarketToken(chainKey, address)` if needed.
15
+ 7. **`sodax.moneyMarket.data.getATokenData(aToken)` returns a plain `Erc20Token`** (`{ name, symbol, decimals, address }`), not a full `XToken`. No `chainKey` / `hubAsset` / `vault` on the result — look up the full `XToken` via `sodax.config.getMoneyMarketToken(chainKey, address)` if needed.
16
16
  8. **Errors → `SodaxError` + `Result<T>`.** v1's `MoneyMarketError<MoneyMarketErrorCode>` is gone. The CODE moved from `error.code` to `error.message`-style? **No** — it's still on `error.code`, but the union changed (see crosswalk below).
17
17
 
18
18
  ## Type / symbol cheat sheet
@@ -192,7 +192,7 @@ Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstCh
192
192
 
193
193
  1. **Forgetting `srcChainKey` + `srcAddress` in params.** TypeScript surfaces this as `error TS1360: Type '{ token, amount, action }' does not satisfy the expected type 'MoneyMarketSupplyParams'`. Add both required fields.
194
194
  2. **Borrow/repay default delivery to source.** Omit `dstChainKey`/`dstAddress` if you want same-chain. Don't pass them as the same value as `srcChainKey` / `srcAddress` — let the default kick in.
195
- 3. **`sodax.moneyMarket.getAToken(...)` returns a partial token.** `Erc20Token & { chainKey }`, not a full `XToken` — no `vault` / `hubAsset` on the result. Look up the full `XToken` via `sodax.config.getMoneyMarketToken(chainKey, address)` separately if you need those fields.
195
+ 3. **`sodax.moneyMarket.data.getATokenData(aToken)` returns a plain `Erc20Token`.** `{ name, symbol, decimals, address }`, not a full `XToken` — no `chainKey` / `vault` / `hubAsset` on the result. Look up the full `XToken` via `sodax.config.getMoneyMarketToken(chainKey, address)` separately if you need those fields.
196
196
  4. **`hubAssets` is gone.** Anything that walked it for vault lookup must use `token.vault` directly.
197
197
  5. **`baseChainInfo[chain].id` is gone — entries have `.key`.** Common in `ChainSelector`-style components.
198
198
  6. **`spokeProvider.chainConfig.chain.type === 'EVM'`** is gone. Use `getChainType(chainKey) === 'EVM'` from `@sodax/sdk`.
@@ -0,0 +1,64 @@
1
+ # Partner migration — v1 → v2
2
+
3
+ Pure-SDK migration playbook for `PartnerService`.
4
+
5
+ Pair: [`features/partner.md`](../../../integration/knowledge/features/partner.md).
6
+
7
+ ## TL;DR
8
+
9
+ 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
+
11
+ ## Type / symbol cheat sheet
12
+
13
+ | Type | v1 shape | v2 shape | Notes |
14
+ |---|---|---|---|
15
+ | Partner action params | non-generic | now generic `<K>` with `srcChainKey`, `srcAddress` | |
16
+ | Partner errors (5 types) | `PartnerFeeClaimError<...>` and 4 siblings | `SodaxError<C>` with `feature: 'partner'` | All 5 v1 typed errors collapse into `SodaxError`, but onto FOUR distinct codes (see crosswalk). |
17
+
18
+ ## v1 → v2 error code crosswalk
19
+
20
+ The v1 partner errors collapse into `SodaxError<C>` with `feature: 'partner'`, but they do NOT all become `EXECUTION_FAILED`. The service emits FOUR distinct codes, with `error.context.action` (and `error.context.method` for reads) discriminating between the operations:
21
+
22
+ - `VALIDATION_FAILED` — same-token guard (output token equals the fee token) in `createIntentAutoSwap` / `swap`.
23
+ - `APPROVE_FAILED` — `approveToken` failure.
24
+ - `EXECUTION_FAILED` — the swap-wait / on-chain execution failure in the auto-swap flow.
25
+ - `LOOKUP_FAILED` — all read methods (`isTokenApproved`, `getUserIntent`, `getIntentDetails`, balance/preference reads, etc.).
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/partner.md.
35
+ + const approved = await sodax.partners.feeClaim.isTokenApproved({ srcChainKey, srcAddress, token });
36
+ + if (approved.ok && !approved.value) {
37
+ + await sodax.partners.feeClaim.approveToken({
38
+ + params: { srcChainKey, srcAddress, token },
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'`.** They span four codes — `VALIDATION_FAILED`, `APPROVE_FAILED`, `EXECUTION_FAILED`, `LOOKUP_FAILED` — not a single `EXECUTION_FAILED`. Discriminate on `error.code` plus `error.context.action` / `error.context.method`.
49
+
50
+ ## Verification
51
+
52
+ ```bash
53
+ pnpm -C <your-app-dir> checkTs
54
+
55
+ # Targeted scans:
56
+ grep -rE "spokeProvider:\s*\w+|isPartnerError\b|PartnerFeeClaimError\b" src/
57
+ ```
58
+
59
+ ## Cross-references
60
+
61
+ - v2 partner usage: [`features/partner.md`](../../../integration/knowledge/features/partner.md).
62
+ - Stuck-asset recovery migration (separate service, new in v2): [`./recovery.md`](recovery.md).
63
+ - Backend API migration (the load-bearing `Result`-wrapping change): [`./backend-api.md`](backend-api.md).
64
+ - Result/error model: [`../breaking-changes/result-and-errors.md`](../breaking-changes/result-and-errors.md).
@@ -0,0 +1,35 @@
1
+ # Recovery migration — v1 → v2
2
+
3
+ Pure-SDK migration playbook for `RecoveryService`.
4
+
5
+ Pair: [`features/recovery.md`](../../../integration/knowledge/features/recovery.md).
6
+
7
+ ## TL;DR
8
+
9
+ **`RecoveryService` is new in v2.** No v1 equivalent — there's no migration to do for code that didn't exist before. This file exists so the v1 → v2 audit doesn't miss the addition.
10
+
11
+ If you have v1 code that worked around the absence (e.g. manually walked the hub wallet abstraction to find stuck assets), replace it with `fetchHubAssetBalances` + `withdrawHubAsset`:
12
+
13
+ ```ts
14
+ const balances = await sodax.recovery.fetchHubAssetBalances({ chainKey, srcAddress });
15
+ if (balances.ok && balances.value.length > 0) {
16
+ await sodax.recovery.withdrawHubAsset({
17
+ params: { /* token (the spoke-side token address, i.e. spokeTokenAddress), amount, srcChainKey, srcAddress (also the withdrawal destination) */ },
18
+ raw: false,
19
+ walletProvider: sonicWp,
20
+ });
21
+ }
22
+ ```
23
+
24
+ See [`features/recovery.md`](../../../integration/knowledge/features/recovery.md) for the full method signatures and error codes.
25
+
26
+ ## Pitfalls
27
+
28
+ 1. **Recovery is not a replacement for real error handling.** Use it after investigating why the original cross-chain operation failed — relay timeouts may resolve on retry; structural failures need fixing first.
29
+
30
+ ## Cross-references
31
+
32
+ - v2 recovery usage: [`features/recovery.md`](../../../integration/knowledge/features/recovery.md).
33
+ - Partner migration (separate service): [`./partner.md`](partner.md).
34
+ - Backend API migration (separate service): [`./backend-api.md`](backend-api.md).
35
+ - Result/error model: [`../breaking-changes/result-and-errors.md`](../breaking-changes/result-and-errors.md).
@@ -26,16 +26,21 @@ Pair: [`features/staking.md`](../../../integration/knowledge/features/staking.md
26
26
  | `InstantUnstakeParams` | `{ amount, minAmount, account, action: 'instantUnstake' }` | `{ srcChainKey, srcAddress, amount, minAmount, action: 'instantUnstake' }` | |
27
27
  | `ClaimParams` | `{ requestId, amount, action: 'claim' }` | `{ srcChainKey, srcAddress, requestId, amount, action: 'claim' }` | Adds chain context. |
28
28
  | `CancelUnstakeParams` | `{ requestId, action: 'cancelUnstake' }` | `{ srcChainKey, srcAddress, requestId, action: 'cancelUnstake' }` | Adds chain context. |
29
- | `getStakingInfo` (read) | `(spokeProvider) => Promise<StakingInfo>` | `(srcAddress, srcChainKey) => Promise<Result<StakingInfo>>` | Renamed to `getStakingInfoFromSpoke` (the v1 `getStakingInfo` was hub-only and is not surfaced now). |
29
+ | `getStakingInfo` (read) | `(spokeProvider) => Promise<StakingInfo>` | `getStakingInfoFromSpoke(srcAddress, srcChainKey) => Promise<Result<StakingInfo>>` (or `getStakingInfo(hubAddress)` if you already have the hub address) | v1 took a `spokeProvider` and resolved internally; v2 splits this into two public reads — `getStakingInfoFromSpoke` for spoke-side resolution, `getStakingInfo` for direct hub-side reads. Both return `Result`. |
30
30
  | `getUnstakingInfo` (read) | `(userAddress, spokeProvider)` | `(srcAddress, srcChainKey)` | v1 ignored `userAddress`; v2 reads it for real. |
31
31
  | `getUnstakingInfoWithPenalty` (read) | new (v2) | `(srcAddress, srcChainKey) => Promise<Result<UnstakingInfo & { requestsWithPenalty: UnstakeRequestWithPenalty[] }>>` | Wraps `getUnstakingInfo`'s base shape with a penalty-augmented request list. |
32
32
 
33
33
  ### Deleted symbols
34
34
 
35
35
  - `StakingError<StakingErrorCode>` and `isStakingError` — replaced by `SodaxError<C>` + `feature: 'staking'`.
36
- - v1 `getStakingInfo(hubAddress, …)` — not exposed as a public method in v2. Use `getStakingInfoFromSpoke(srcAddress, srcChainKey)`; the SDK derives the hub wallet via `HubService.getUserHubWalletAddress` internally.
37
36
  - `spokeProvider instanceof SonicSpokeProvider` runtime checks — replace with `isHubChainKeyType(chainKey)` from `@sodax/sdk`.
38
37
 
38
+ ### Renamed / re-shaped (not deleted)
39
+
40
+ - v1 `getStakingInfo(spokeProvider)` had implicit spoke-side resolution. v2 surfaces two public reads instead:
41
+ - `getStakingInfoFromSpoke(srcAddress, srcChainKey)` — for the spoke-side flow; derives the hub wallet via `hubProvider.getUserHubWalletAddress` internally.
42
+ - `getStakingInfo(hubAddress: Address)` — direct hub-side read, kept public for when the hub address is already known.
43
+
39
44
  ### v1 → v2 error code crosswalk (staking-specific)
40
45
 
41
46
  | v1 `StakingErrorCode` | v2 code + context |
@@ -119,7 +124,7 @@ Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstCh
119
124
  1. **Wrong return shape for actions.** Treating `stake/unstake/etc.` as returning `Result<TxReturnType<K, false>>` (single hash) is **wrong** — they return `Result<TxHashPair>` because they always relay spoke→hub. Only `approve` returns a single hash.
120
125
  2. **Forgetting `raw: true` on the allowance query.** TypeScript error: `Property 'walletProvider' is missing`. `isAllowanceValid` requires `WalletProviderSlot<K, Raw>`; `raw: false` would force a wallet provider. Use `raw: true` for read-only.
121
126
  3. **Forgetting to remove the v1 `account` field from params.** v2 uses `srcAddress`. If both are set, TypeScript rejects the literal.
122
- 4. **`getStakingInfo(hubAddress)` is not a public method in v2.** v1 had it for direct hub queries. v2 has `getStakingInfoFromSpoke(srcAddress, srcChainKey)` which derives the hub wallet internally. Use the spoke variant.
127
+ 4. **Confusing `getStakingInfo` and `getStakingInfoFromSpoke`.** Both are public in v2 — pick by which address you have. `getStakingInfo(hubAddress: Address)` reads the hub wallet directly; `getStakingInfoFromSpoke(srcAddress, srcChainKey)` derives the hub wallet from a spoke address via `hubProvider.getUserHubWalletAddress`, then delegates. Passing a spoke address into `getStakingInfo` returns wrong data (no hub-wallet resolution); always use the spoke variant when starting from a spoke address.
123
128
  5. **`UnstakingInfo` no longer accepts `userAddress` separately.** v1 took both `spokeProvider` and `userAddress` props but ignored `userAddress` inside. v2 takes `srcAddress` and uses it.
124
129
 
125
130
  ## Verification