@sodax/skills 2.0.0-rc.9 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (163) hide show
  1. package/.claude-plugin/plugin.json +1 -9
  2. package/AGENTS.md +119 -14
  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/money-market.md +6 -1
  28. package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
  29. package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
  30. package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
  31. package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
  32. package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md +8 -8
  33. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +168 -0
  34. package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
  35. package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +4 -4
  36. package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
  37. package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md +3 -0
  38. package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md +1 -1
  39. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +67 -6
  40. package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +49 -0
  41. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +54 -0
  42. package/skills/sodax-dapp-kit/migration/SKILL.md +64 -0
  43. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md +1 -1
  44. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +2 -2
  45. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md +1 -1
  46. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md +1 -1
  47. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +19 -10
  48. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md +2 -2
  49. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
  50. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
  51. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +3 -3
  52. package/skills/sodax-dapp-kit/money-market/SKILL.md +61 -0
  53. package/skills/sodax-dapp-kit/staking/SKILL.md +60 -0
  54. package/skills/sodax-dapp-kit/swap/SKILL.md +64 -0
  55. package/skills/sodax-sdk/SKILL.md +11 -6
  56. package/skills/sodax-sdk/backend-api/SKILL.md +21 -15
  57. package/skills/sodax-sdk/bridge/SKILL.md +4 -0
  58. package/skills/sodax-sdk/dex/SKILL.md +5 -1
  59. package/skills/sodax-sdk/integration/knowledge/README.md +1 -1
  60. package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
  61. package/skills/sodax-sdk/integration/knowledge/architecture.md +24 -21
  62. package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
  63. package/skills/sodax-sdk/integration/knowledge/features/README.md +2 -1
  64. package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +27 -16
  65. package/skills/sodax-sdk/integration/knowledge/features/bridge.md +15 -14
  66. package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
  67. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +175 -0
  68. package/skills/sodax-sdk/integration/knowledge/features/migration.md +73 -28
  69. package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
  70. package/skills/sodax-sdk/integration/knowledge/features/partner.md +27 -4
  71. package/skills/sodax-sdk/integration/knowledge/features/recovery.md +5 -4
  72. package/skills/sodax-sdk/integration/knowledge/features/staking.md +2 -2
  73. package/skills/sodax-sdk/integration/knowledge/features/swap.md +42 -24
  74. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
  75. package/skills/sodax-sdk/integration/knowledge/quickstart.md +1 -1
  76. package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -0
  77. package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
  78. package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
  79. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +34 -2
  80. package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +102 -0
  81. package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +28 -4
  82. package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
  83. package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
  84. package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
  85. package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +40 -4
  86. package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +32 -9
  87. package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
  88. package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -4
  89. package/skills/sodax-sdk/leverage-yield/SKILL.md +50 -0
  90. package/skills/sodax-sdk/migration/SKILL.md +5 -1
  91. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
  92. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
  93. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
  94. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +3 -3
  95. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -5
  96. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +1 -1
  97. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +23 -23
  98. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
  99. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
  100. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/migration.md +29 -27
  101. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
  102. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +10 -5
  103. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +2 -2
  104. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +2 -2
  105. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
  106. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +18 -16
  107. package/skills/sodax-sdk/money-market/SKILL.md +7 -3
  108. package/skills/sodax-sdk/partner/SKILL.md +4 -0
  109. package/skills/sodax-sdk/recovery/SKILL.md +5 -1
  110. package/skills/sodax-sdk/staking/SKILL.md +4 -0
  111. package/skills/sodax-sdk/swap/SKILL.md +8 -3
  112. package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
  113. package/skills/sodax-wallet-sdk-core/SKILL.md +7 -3
  114. package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +54 -0
  115. package/skills/sodax-wallet-sdk-core/evm/SKILL.md +54 -0
  116. package/skills/sodax-wallet-sdk-core/icon/SKILL.md +54 -0
  117. package/skills/sodax-wallet-sdk-core/injective/SKILL.md +54 -0
  118. package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
  119. package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +2 -2
  120. package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
  121. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
  122. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
  123. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
  124. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
  125. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
  126. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
  127. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
  128. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
  129. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
  130. package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
  131. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
  132. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
  133. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/testing.md +1 -1
  134. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
  135. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
  136. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
  137. package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
  138. package/skills/sodax-wallet-sdk-core/near/SKILL.md +54 -0
  139. package/skills/sodax-wallet-sdk-core/solana/SKILL.md +54 -0
  140. package/skills/sodax-wallet-sdk-core/stacks/SKILL.md +53 -0
  141. package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +54 -0
  142. package/skills/sodax-wallet-sdk-core/sui/SKILL.md +53 -0
  143. package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
  144. package/skills/sodax-wallet-sdk-react/bridge-to-sdk/SKILL.md +56 -0
  145. package/skills/sodax-wallet-sdk-react/connect/SKILL.md +59 -0
  146. package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
  147. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
  148. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
  149. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +10 -10
  150. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
  151. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +4 -4
  152. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
  153. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
  154. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
  155. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
  156. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
  157. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
  158. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/ssr-setup.md +24 -19
  159. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +1 -1
  160. package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +51 -0
  161. package/skills/sodax-wallet-sdk-react/switch-chain/SKILL.md +51 -0
  162. package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +54 -0
  163. package/skills/sodax-wallet-sdk-react/walletconnect/SKILL.md +52 -0
@@ -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;
@@ -7,9 +7,9 @@ Pair: [`features/migration.md`](../../../integration/knowledge/features/migratio
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/migration.md`](../../../integration/knowledge/features/migratio
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/migration.md`](../../../integration/knowledge/features/migratio
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
 
@@ -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`.
@@ -13,11 +13,16 @@ Standard pattern. Drop `spokeProvider`; pass `walletProvider`. Add `srcChainKey`
13
13
  | Type | v1 shape | v2 shape | Notes |
14
14
  |---|---|---|---|
15
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. |
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
17
 
18
18
  ## v1 → v2 error code crosswalk
19
19
 
20
- All 5 v1 partner error codes map to `EXECUTION_FAILED` with `error.context.action` discriminating between the operations.
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.).
21
26
 
22
27
  ## Per-method delta
23
28
 
@@ -27,10 +32,10 @@ Partner operations live on `sodax.partners.feeClaim` (a `PartnerFeeClaimService`
27
32
  - await sodax.partners.claimFees({ /* … */ }, spokeProvider);
28
33
  + // Approve once, then configure auto-swap preference, then run swaps.
29
34
  + // Full method list lives in integration/features/partner.md.
30
- + const approved = await sodax.partners.feeClaim.isTokenApproved({ token, srcAddress });
35
+ + const approved = await sodax.partners.feeClaim.isTokenApproved({ srcChainKey, srcAddress, token });
31
36
  + if (approved.ok && !approved.value) {
32
37
  + await sodax.partners.feeClaim.approveToken({
33
- + params: { token, amount },
38
+ + params: { srcChainKey, srcAddress, token },
34
39
  + raw: false,
35
40
  + walletProvider,
36
41
  + });
@@ -40,7 +45,7 @@ Partner operations live on `sodax.partners.feeClaim` (a `PartnerFeeClaimService`
40
45
  ## Pitfalls
41
46
 
42
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.
43
- 2. **All 5 v1 partner errors collapse to `feature: 'partner'`.** Even though they share the `EXECUTION_FAILED` code with every other feature.
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`.
44
49
 
45
50
  ## Verification
46
51
 
@@ -11,10 +11,10 @@ Pair: [`features/recovery.md`](../../../integration/knowledge/features/recovery.
11
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
12
 
13
13
  ```ts
14
- const balances = await sodax.recovery.fetchHubAssetBalances({ /* user / hub-wallet args */ });
14
+ const balances = await sodax.recovery.fetchHubAssetBalances({ chainKey, srcAddress });
15
15
  if (balances.ok && balances.value.length > 0) {
16
16
  await sodax.recovery.withdrawHubAsset({
17
- params: { /* hub-asset address, amount, destination spoke chain + address */ },
17
+ params: { /* token (the spoke-side token address, i.e. spokeTokenAddress), amount, srcChainKey, srcAddress (also the withdrawal destination) */ },
18
18
  raw: false,
19
19
  walletProvider: sonicWp,
20
20
  });
@@ -38,7 +38,7 @@ Pair: [`features/staking.md`](../../../integration/knowledge/features/staking.md
38
38
  ### Renamed / re-shaped (not deleted)
39
39
 
40
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 `HubService.getUserHubWalletAddress` internally.
41
+ - `getStakingInfoFromSpoke(srcAddress, srcChainKey)` — for the spoke-side flow; derives the hub wallet via `hubProvider.getUserHubWalletAddress` internally.
42
42
  - `getStakingInfo(hubAddress: Address)` — direct hub-side read, kept public for when the hub address is already known.
43
43
 
44
44
  ### v1 → v2 error code crosswalk (staking-specific)
@@ -124,7 +124,7 @@ Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstCh
124
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.
125
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.
126
126
  3. **Forgetting to remove the v1 `account` field from params.** v2 uses `srcAddress`. If both are set, TypeScript rejects the literal.
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 `HubService.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.
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.
128
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.
129
129
 
130
130
  ## Verification
@@ -13,7 +13,7 @@ Pair: [`features/swap.md`](../../../integration/knowledge/features/swap.md).
13
13
  - `dstChain` → `dstChainKey`
14
14
  - **`Intent.srcChain` / `Intent.dstChain` are unchanged** (read shape) — they're `IntentRelayChainId` (bigint).
15
15
  4. **`CreateIntentResult` shape changed.** v1 was a tuple `[spokeTxHash, intent, relayData]`; v2 is an object `{ tx, intent, relayData }`. Destructure accordingly.
16
- 5. **`SubmitSwapTxRequest.srcChainId` → `srcChainKey`.** And `relayData` field on the request expects a **string** (`relayData.payload`), not the `RelayExtraData` object.
16
+ 5. **Backend submit-tx moved to `sodax.api.swaps.submitTx`** (`SubmitTxRequestV2`, was v1 `SubmitSwapTxRequest`): `srcChainId` → `srcChainKey`, and `relayData` expects a **string** (`relayData.payload`), not the `RelayExtraData` object.
17
17
  6. **Errors → `SodaxError` + `Result<T>`.** v1's `IntentError<IntentErrorCode>` is gone. Branch on `result.ok`; use `(error.feature, error.code)` for discrimination.
18
18
 
19
19
  ## Type / symbol cheat sheet
@@ -24,7 +24,7 @@ Pair: [`features/swap.md`](../../../integration/knowledge/features/swap.md).
24
24
  |---|---|---|---|
25
25
  | `CreateIntentParams` (request) | `srcChain`, `dstChain` | `srcChainKey`, `dstChainKey` | Now generic: `CreateIntentParams<K extends SpokeChainKey>`. |
26
26
  | `CreateLimitOrderParams` (request) | `srcChain`, `dstChain` | `srcChainKey`, `dstChainKey` | `Omit<CreateIntentParams<K>, 'deadline'>`. |
27
- | `SubmitSwapTxRequest` (backend req) | `srcChainId` | `srcChainKey` | And `relayData: string` (was the object in v1). |
27
+ | `SubmitTxRequestV2` (backend req, was `SubmitSwapTxRequest`) | `srcChainId` | `srcChainKey` | Submitted via `sodax.api.swaps.submitTx`; `relayData: string` (was the object in v1). |
28
28
  | `Intent` (read shape) | `srcChain`, `dstChain` | **unchanged** | `IntentRelayChainId` (bigint). Don't grep-replace blindly. |
29
29
  | `XToken` | `xChainId` | `chainKey` | Type renamed from `Token` → `XToken`. |
30
30
  | `CreateIntentResult` | tuple `[spokeTxHash, intent, relayData]` | object `{ tx, intent, relayData }` | Generic: `CreateIntentResult<K, Raw>`. |
@@ -63,7 +63,8 @@ Pair: [`features/swap.md`](../../../integration/knowledge/features/swap.md).
63
63
  + walletProvider: sourceWalletProvider,
64
64
  + });
65
65
  + if (!result.ok) return;
66
- + const { spokeTxHash, intent, relayData } = result.value;
66
+ + const { solverExecutionResponse, intent, intentDeliveryInfo } = result.value;
67
+ + // swap() returns SwapResponse = { solverExecutionResponse, intent, intentDeliveryInfo }
67
68
  ```
68
69
 
69
70
  ### `createIntent`
@@ -110,19 +111,22 @@ const result = await sodax.swaps.isAllowanceValid({ params, raw: true });
110
111
 
111
112
  The underlying read doesn't consult the wallet provider; `raw: true` is the contract for read-only access.
112
113
 
113
- ### Backend submit-tx (`SubmitSwapTxRequest`)
114
+ ### Backend submit-tx (`SubmitTxRequestV2`)
114
115
 
115
116
  ```diff
116
- const request: SubmitSwapTxRequest = {
117
+ - const request: SubmitSwapTxRequest = {
118
+ + const request: SubmitTxRequestV2 = {
117
119
  txHash: spokeTxHash as string,
118
120
  - srcChainId: sourceChain,
119
121
  + srcChainKey: src.chain,
120
122
  walletAddress: sourceAccount.address ?? '',
121
- intent: swapIntentData,
123
+ - intent: swapIntentData, // was: V1 string/number-downcast shape
124
+ + intent, // IntentRequestV2 — the createIntent intent passes through (bigint)
122
125
  - relayData, // was the RelayExtraData object
123
126
  + relayData: relayData.payload, // now a string
124
127
  };
125
- const submitResult = await sodax.backendApi.submitSwapTx(request);
128
+ - const submitResult = await sodax.backendApi.submitSwapTx(request);
129
+ + const submitResult = await sodax.api.swaps.submitTx(request); // moved off BackendApiService
126
130
  if (!submitResult.ok) return;
127
131
  ```
128
132
 
@@ -144,24 +148,24 @@ The underlying read doesn't consult the wallet provider; `raw: true` is the cont
144
148
  if (!createIntentResult.ok) return;
145
149
  - const [spokeTxHash, intent, relayData] = createIntentResult.value;
146
150
  + const { tx: spokeTxHash, intent, relayData } = createIntentResult.value;
147
- const swapIntentData: SwapIntentData = {
148
- /* … */
149
- - srcChain: Number(intent.srcChain), // Intent.srcChain still on read shape
150
- - dstChain: Number(intent.dstChain), // Intent.dstChain still on read shape
151
- + srcChain: Number(intent.srcChain), // unchanged — Intent shape kept these
152
- + dstChain: Number(intent.dstChain),
153
- };
154
- const request: SubmitSwapTxRequest = {
151
+ - const swapIntentData: SwapIntentData = {
152
+ - /* … string/number downcasts of intent.* … */
153
+ - srcChain: Number(intent.srcChain),
154
+ - dstChain: Number(intent.dstChain),
155
+ - };
156
+ - const request: SubmitSwapTxRequest = {
157
+ + const request: SubmitTxRequestV2 = {
155
158
  txHash: spokeTxHash as string,
156
159
  - srcChainId: sourceChain,
157
160
  + srcChainKey: src.chain,
158
161
  walletAddress: sourceAccount.address ?? '',
159
- intent: swapIntentData,
162
+ - intent: swapIntentData,
163
+ + intent, // IntentRequestV2 — bigint fields pass through, no downcast
160
164
  - relayData,
161
165
  + relayData: relayData.payload,
162
166
  };
163
167
  - await submitSwapTx(request);
164
- + const submitResult = await sodax.backendApi.submitSwapTx(request);
168
+ + const submitResult = await sodax.api.swaps.submitTx(request);
165
169
  + if (!submitResult.ok) return;
166
170
  };
167
171
  ```
@@ -172,7 +176,7 @@ Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstCh
172
176
 
173
177
  1. **Over-broad regex on `srcChain` / `dstChain`.** Request types renamed; `Intent` (read shape) didn't. Distinguish "I'm building a request" from "I'm reading an intent."
174
178
  2. **`createIntent` success shape changed from tuple to object.** `{ tx, intent, relayData }`, not `[spokeTxHash, intent, relayData]`.
175
- 3. **`relayData` on `SubmitSwapTxRequest` is a `string`.** It's `relayData.payload`, not the full `RelayExtraData` object.
179
+ 3. **`relayData` on `SubmitTxRequestV2` is a `string`.** It's `relayData.payload`, not the full `RelayExtraData` object.
176
180
  4. **`spokeTxHash` is `TxReturnType<K, false>`, not necessarily `string`.** For most chains it's a string already, but the SDK type is broader. Cast at the boundary when passing to APIs that strictly want `string`: `txHash: spokeTxHash as string`.
177
181
  5. **`Intent.deadline` is `bigint`.** `Math.floor(Date.now() / 1000) + 60 * 5` returns a number; wrap in `BigInt(...)`.
178
182
  6. **`IntentResponse.srcChain` / `dstChain` from the backend are `IntentRelayChainId` (number/bigint), not chain keys.** Convert via `sodax.config.getSpokeChainKeyFromIntentRelayChainId(BigInt(intent.dstChain))` when displaying.
@@ -1,19 +1,19 @@
1
1
  # `SodaxConfig` constructor reshape
2
2
 
3
- The v2 `Sodax` constructor accepts a `DeepPartial<SodaxConfig>`. Several config fields renamed, moved, or were added between v1 and v2; if your project passed a custom config, check these.
3
+ The v2 `Sodax` constructor accepts a `SodaxOptions` (`DeepPartial<SodaxDefaultConfig> & SodaxOptionalConfig`). Several config fields renamed, moved, or were added between v1 and v2; if your project passed a custom config, check these.
4
4
 
5
- ## v2 `SodaxConfig` shape (source of truth)
5
+ ## v2 config data shape (`SodaxDefaultConfig`, source of truth)
6
6
 
7
- Defined in `@sodax/types` (`packages/types/src/sodax-config/sodax-config.ts`):
7
+ Defined in `@sodax/types` (`packages/types/src/sodax-config/sodax-config.ts`). This is the static data contract the backend serves and the packaged defaults are built from; `SodaxConfig` is the merged result (`SodaxDefaultConfig & SodaxOptionalConfig`):
8
8
 
9
9
  ```ts
10
- type SodaxConfig = {
11
- fee: PartnerFee | undefined; // global partner fee (overridable per-feature)
10
+ type SodaxDefaultConfig = {
12
11
  chains: Record<SpokeChainKey, SpokeChainConfig>; // per-spoke-chain config (rpcUrl + tx polling + chain-specific shape)
13
- swaps: SwapsConfig; // supported swap tokens per chain
14
- moneyMarket: MoneyMarketConfig; // money market service config
15
- bridge: BridgeConfig; // bridge partner-fee override
16
- dex: DexConfig; // DEX service config
12
+ swaps: SwapsDefaultConfig; // supported swap tokens per chain (+ per-feature partnerFee override)
13
+ moneyMarket: MoneyMarketDefaultConfig; // money market service config (+ per-feature partnerFee override)
14
+ bridge: BridgeDefaultConfig; // bridge partner-fee override
15
+ dex: DexDefaultConfig; // DEX service config
16
+ leverageYield: LeverageYieldDefaultConfig; // leverage-yield ERC-4626 vault registry (+ per-feature partnerFee override)
17
17
  hub: HubConfig; // hub-chain (Sonic) provider config
18
18
  api: ApiConfig; // backend API endpoint
19
19
  solver: SolverConfig; // intent solver endpoint + contracts
@@ -21,7 +21,9 @@ type SodaxConfig = {
21
21
  };
22
22
  ```
23
23
 
24
- A matching default `sodaxConfig` const is exported from the same module — `new Sodax()` deep-merges your `DeepPartial<SodaxConfig>` over it.
24
+ A matching default `sodaxConfig` const is exported from the same module — `new Sodax()` deep-merges your `DeepPartial<SodaxDefaultConfig>` over it.
25
+
26
+ The `new Sodax(...)` argument is actually `SodaxOptions = DeepPartial<SodaxDefaultConfig> & SodaxOptionalConfig`, where `SodaxOptionalConfig` carries the client-side options `{ logger?; fee? }` plus the per-feature option objects. The global partner `fee` and `logger` are **client-side options, NOT `SodaxDefaultConfig` data fields**: the integrator sets them, they are resolved once, and they are never fetched from or overwritten by the backend config. Read the resolved global fee back via `sodax.config.fee`. It is the **fallback applied to any feature whose own `partnerFee` is unset** (effective fee = `featureFee ?? fee`, via `sodax.config.swapPartnerFee` / `moneyMarketPartnerFee` / `bridgePartnerFee` / `leverageYieldPartnerFee`). (Per-feature partner-fee overrides — `swaps.partnerFee`, `moneyMarket.partnerFee`, `bridge.partnerFee`, `leverageYield.partnerFee` — live on the feature options.)
25
27
 
26
28
  ## v1 shape (for reference)
27
29
 
@@ -47,7 +49,7 @@ All v1 fields were **optional**. v1 had **no** top-level `rpcConfig` on `SodaxCo
47
49
 
48
50
  | v1 location | v2 location | Notes |
49
51
  |---|---|---|
50
- | `SodaxConfig.swaps` (`SolverConfigParams` — `{ intentsContract, solverApiEndpoint, protocolIntentsContract?, partnerFee? }`) | **Split into two:** `SodaxConfig.solver: SolverConfig` (`{ intentsContract, solverApiEndpoint, protocolIntentsContract }`) and `SodaxConfig.swaps: SwapsConfig` (supported tokens per chain — new in v2). | v1 partner-fee inside `SolverConfigParams` moves to the global `SodaxConfig.fee` slot or per-feature configs. |
52
+ | `SodaxConfig.swaps` (`SolverConfigParams` — `{ intentsContract, solverApiEndpoint, protocolIntentsContract?, partnerFee? }`) | **Split into two:** `SodaxConfig.solver: SolverConfig` (`{ intentsContract, solverApiEndpoint, protocolIntentsContract }`) and `SodaxConfig.swaps: SwapsConfig` (supported tokens per chain — new in v2). | v1 partner-fee inside `SolverConfigParams` moves to the global `SodaxOptions.fee` option or per-feature configs. |
51
53
  | `SodaxConfig.hubProviderConfig` (`EvmHubProviderConfig` — `{ hubRpcUrl, chainConfig }`) | **`SodaxConfig.hub`** (`HubConfig` — full hub addresses + native token + bnUSD + polling + RPC URL). | Field renamed `hubProviderConfig` → `hub`. Shape expanded: v1 just had RPC URL + chain config; v2 ships the full hub-contract address map. |
52
54
  | `SodaxConfig.moneyMarket` (`MoneyMarketConfigParams`) | `SodaxConfig.moneyMarket` (`MoneyMarketConfig` — required, shape changed). | Reshape, see `@sodax/types/src/common/common.ts` MoneyMarketConfig. |
53
55
  | `SodaxConfig.bridge` (`BridgeServiceConfig`) | `SodaxConfig.bridge` (`BridgeConfig` — `{ partnerFee }`). | Reshape; smaller. |
@@ -58,7 +60,7 @@ All v1 fields were **optional**. v1 had **no** top-level `rpcConfig` on `SodaxCo
58
60
  | `SodaxConfig.migration` (`MigrationServiceConfig`) | **Removed.** Migration service runs with hard-coded defaults. | No replacement on `SodaxConfig`. v2 surfaces customization via per-method params on `sodax.migration.*`, not constructor config — see [`../features/migration.md`](../features/migration.md). |
59
61
  | `SodaxConfig.partners` (`PartnerServiceConfig`) | **Removed.** Partner service runs with defaults. | Per-claim partner-fee config now flows via call-level params on `sodax.partners.*` methods. |
60
62
  | `SodaxConfig.sharedConfig` (`typeof defaultSharedConfig`) | **Removed.** | Absorbed into `ConfigService` + per-chain `SpokeChainConfig`. Override individual chains via `SodaxConfig.chains[key]`. |
61
- | (none in v1) | **`SodaxConfig.fee: PartnerFee \| undefined`** (new). | Global partner-fee, applies to all features unless overridden by feature-level config (`bridge.partnerFee`, money market, etc.). |
63
+ | (none in v1) | **`SodaxOptions.fee?: PartnerFee`** (new — a client-side option, NOT a `SodaxConfig` data field). | Global partner fee, set via `new Sodax({ fee })` and read back on `sodax.config.fee`. A client option like `logger` — never fetched from or overwritten by the backend. Per-feature overrides still live on `SodaxConfig` (`bridge.partnerFee`, `swaps.partnerFee`, `moneyMarket.partnerFee`). |
62
64
  | (v1 had no top-level `configService` injection slot on `SodaxConfig` — `ConfigService` was always constructed internally from `backendApiConfig` + `sharedConfig`.) | Same — `ConfigService` is internal. v2 does **not** expose a typed slot to inject a custom `IConfigApi` either. To swap the backend in tests, point `SodaxConfig.api.baseURL` at a mock server. | See Pitfall below. |
63
65
 
64
66
  Migration:
@@ -79,7 +81,7 @@ Migration:
79
81
  - // RPC URLs were passed as a SEPARATE prop on the framework-layer SodaxProvider
80
82
  - // (alongside the sodaxConfig). The Sodax constructor itself never saw rpcConfig.
81
83
 
82
- + // v2 — DeepPartial<SodaxConfig> passed directly to new Sodax(...)
84
+ + // v2 — SodaxOptions (DeepPartial<SodaxDefaultConfig> & client options) passed directly to new Sodax(...)
83
85
  + const sodax = new Sodax({
84
86
  + hub: { /* HubConfig — usually omit, default ships full hub addresses */ },
85
87
  + solver: {
@@ -91,7 +93,7 @@ Migration:
91
93
  + supportedTokens: { /* per-chain table */ },
92
94
  + },
93
95
  + relay: { /* RelayConfig — relayer URL + chain-id map */ },
94
- + fee: { address: '0x…', percentage: 10 }, // global partner fee (moved out of swaps)
96
+ + fee: { address: '0x…', percentage: 10 }, // global partner fee — a SodaxOptions client option (not SodaxConfig data)
95
97
  + chains: {
96
98
  + [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://…' },
97
99
  + [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://…' },
@@ -113,12 +115,12 @@ See [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md)
113
115
 
114
116
  ### Pitfall
115
117
 
116
- If you previously injected a custom `ConfigService` for testing (a v1 escape hatch), v2 doesn't accept one at the top level — and unlike what earlier doc versions claimed, **v2 also doesn't expose a typed slot to inject a custom `IConfigApi`**. The realistic options:
118
+ If you previously injected a custom `ConfigService` for testing (a v1 escape hatch), v2 doesn't accept one at the top level — and unlike what earlier doc versions claimed, **v2 also doesn't expose a typed slot to inject a custom `IConfigApiV1`**. The realistic options:
117
119
 
118
120
  - Point `SodaxConfig.api.baseURL` at a local mock backend server.
119
121
  - Construct your own `BackendApiService`-compatible object in your app/test bootstrap and swap it in where you control the `Sodax` instance.
120
122
 
121
- The `SodaxConfig.api` field is `ApiConfig` (`{ baseURL, timeout, headers }`) — there is no `api.api` sub-field for IConfigApi injection.
123
+ The `SodaxConfig.api` field is `ApiConfig` (`{ baseURL, timeout, headers }`) — there is no `api.api` sub-field for IConfigApiV1 injection.
122
124
 
123
125
  ### Pitfall — module-scope reads
124
126
 
@@ -1,6 +1,10 @@
1
1
  ---
2
2
  name: sodax-sdk-money-market
3
3
  description: 'Granular skill for the @sodax/sdk v2 money-market feature only — cross-chain lending and borrowing (supply, borrow, withdraw, repay) and per-position reads. Use when the consumer task is specifically money-market (e.g. "supply on Sodax", "borrow against my position", "Sodax lending", "withdraw collateral", "repay debt", "cross-chain borrow"). Covers BOTH integration (write new v2 code) and migration (port v1 MoneyMarketService to v2). Skill links into the parent sodax-sdk knowledge tree — does NOT duplicate it. For React dapps, prefer the sodax-dapp-kit skill.'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
4
8
  ---
5
9
 
6
10
  # Money Market (Core SDK granular skill)
@@ -13,7 +17,7 @@ Granular skill for the lending/borrowing feature of `@sodax/sdk` v2. Access via
13
17
  2. **Which operation?** `supply`, `borrow`, `withdraw`, `repay`, or just position reads.
14
18
  3. **Same-chain or cross-chain borrow?** `borrow` can deliver funds back to the source chain or to a different spoke chain.
15
19
  4. **Signed flow or unsigned-tx (`createXxxIntent`)?**
16
- 5. **Need user-position reads** (aToken balance, reserves data, formatted summaries)? Those come from `sodax.backendApi`, not `MoneyMarketService` — load [`../backend-api/SKILL.md`](../backend-api/SKILL.md) alongside.
20
+ 5. **Need reserves / position reads** (aToken balances, reserves data, formatted summaries)? Those live on `sodax.moneyMarket.data`. Backend-indexed user position (`getMoneyMarketPosition`, asset lists) comes from `sodax.backendApi` — load [`../backend-api/SKILL.md`](../backend-api/SKILL.md) alongside.
17
21
 
18
22
  ## Integration workflow
19
23
 
@@ -28,9 +32,9 @@ Granular skill for the lending/borrowing feature of `@sodax/sdk` v2. Access via
28
32
 
29
33
  ### Money-market-specific anti-patterns
30
34
 
31
- - **Confusing `token` (hub asset address) with the spoke-chain token address.** `MoneyMarketParams<K>.token` is the hub asset (a `0x...` address on Sonic), not the user's spoke-chain ERC20.
35
+ - **Passing the hub asset address as `token`.** `MoneyMarketParams<K>.token` is the user's spoke-chain original asset address (e.g. `USDC_ARBITRUM.address` with `srcChainKey: ARBITRUM_MAINNET`), validated via `getSpokeTokenFromOriginalAssetAddress`; the hub asset is derived internally. Don't substitute a hub (`0x…` on Sonic) address.
32
36
  - **Skipping allowance check before `supply` / `repay`.** Use `isAllowanceValid` then `approve` with the action-discriminated args.
33
- - **Calling reserve-data reads on `MoneyMarketService`.** Those live on `sodax.backendApi`.
37
+ - **Routing reserve-data reads to `sodax.backendApi`.** Those live on `sodax.moneyMarket.data` (`getReservesData`, `getUserReservesData`, `getATokensBalances`, `getReservesHumanized`, `getUserReservesHumanized`, `formatUserSummary`).
34
38
 
35
39
  ## Migration workflow (v1 → v2)
36
40
 
@@ -1,6 +1,10 @@
1
1
  ---
2
2
  name: sodax-sdk-partner
3
3
  description: 'Granular skill for the @sodax/sdk v2 partner-fee feature only — `PartnerService` (operations on `sodax.partners.feeClaim`). Token approval on the hub, auto-swap preferences, immediate fee-claim swap, intent-driven auto-swap, asset-balance reads. Use when the task is partner-fee work (e.g. "claim partner fee", "configure partner auto-swap preference", "approve partner fee token on Sodax hub", "Sodax PartnerService"). Covers BOTH integration and migration. 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
4
8
  ---
5
9
 
6
10
  # Partner (Core SDK granular skill)
@@ -1,6 +1,10 @@
1
1
  ---
2
2
  name: sodax-sdk-recovery
3
3
  description: 'Granular skill for the @sodax/sdk v2 recovery feature only — `RecoveryService` for withdrawing stuck hub-wallet assets back to a spoke chain. Use when the task is recovering assets stranded on the hub after a failed cross-chain operation (e.g. "recover stuck assets on Sonic", "Sodax RecoveryService", "fetchHubAssetBalances", "withdrawHubAsset", "stuck-asset withdrawal"). Service is NEW in v2 (no v1 equivalent). Covers BOTH integration and the v2-only migration note. Skill links into the parent sodax-sdk knowledge tree.'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
4
8
  ---
5
9
 
6
10
  # Recovery (Core SDK granular skill)
@@ -27,7 +31,7 @@ Granular skill for `RecoveryService` — `sodax.recovery`. Feature tag for error
27
31
  ### Recovery-specific anti-patterns
28
32
 
29
33
  - **Treating recovery as a routine flow.** It's a workaround for failures; calling it on successfully completed flows wastes gas and confuses users.
30
- - **Skipping the balance read.** `fetchHubAssetBalances` returns the full set of hub assets for a user; pick the one to withdraw rather than guessing the address.
34
+ - **Skipping the balance read.** `fetchHubAssetBalances` returns only the non-zero hub-asset balances for one spoke chain (it takes `{ chainKey, srcAddress }` and excludes leverage-yield vault share tokens); pick the entry to withdraw rather than guessing the address.
31
35
  - **Ignoring the underlying failure.** Recovery moves the asset but doesn't explain why the original op failed — investigate first (relay timeout? bad params? destination chain issue?).
32
36
 
33
37
  ## Migration workflow (v1 → v2)
@@ -1,6 +1,10 @@
1
1
  ---
2
2
  name: sodax-sdk-staking
3
3
  description: 'Granular skill for the @sodax/sdk v2 staking feature only — SODA ↔ xSoda staking via ERC-4626 vault. Stake, unstake (with penalty curve), instant unstake (slippage), claim, cancel unstake. Use when the task is staking (e.g. "stake SODA", "unstake xSoda", "claim Sodax staking rewards", "instant unstake with penalty", "cancel pending unstake", "get staking info from spoke"). Covers BOTH integration and migration. 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
4
8
  ---
5
9
 
6
10
  # Staking (Core SDK granular skill)
@@ -1,6 +1,10 @@
1
1
  ---
2
2
  name: sodax-sdk-swap
3
3
  description: 'Granular skill for the @sodax/sdk v2 swap feature only — intent-based swaps via solver (market orders + limit orders) and cancel/approve flows. Use when the consumer has decided the task is a swap (e.g. "swap with Sodax", "Sodax intent swap", "limit order on Sodax", "cross-chain swap via Sonic", "cancel a Sodax intent") and you want to skip loading the broad sodax-sdk skill. Covers BOTH integration (write new v2 swap code) and migration (port v1 swap to v2) — picks via Step 1 question. Skill is intentionally short and links into the parent sodax-sdk knowledge tree (../integration/knowledge/, ../migration-v1-to-v2/knowledge/) for full reference. For React dapps doing swaps, prefer the sodax-dapp-kit skill instead.'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
4
8
  ---
5
9
 
6
10
  # Swap (Core SDK granular skill)
@@ -19,7 +23,7 @@ Swap has materially different code paths depending on the answers. Don't skip:
19
23
  - Unsigned → `raw: true`, you handle relay yourself.
20
24
  3. **One-shot `swap()` or step-by-step (`createIntent` → backend submit → `postExecution`)?**
21
25
  - One-shot is the default for frontends. Step-by-step is for backends that already have a relay/orchestration layer.
22
- 4. **Market order or limit order?** Limit orders use a different params shape (no `deadline`).
26
+ 4. **Market order or limit order?** Limit orders use a different params shape — `deadline` becomes optional (forced to `0n` internally), not required.
23
27
 
24
28
  ## Integration workflow (writing new v2 swap code)
25
29
 
@@ -37,7 +41,7 @@ Read in order. Skipping `ai-rules.md` is the most common cause of agents reverti
37
41
 
38
42
  - **`try { await sodax.swaps.swap(...) } catch` for SDK-level failures.** v2 returns `Result<T>` — branch on `result.ok`. `catch` only fires for thrown exceptions (e.g. missing `walletProvider`), not for `RELAY_TIMEOUT` or `EXECUTION_FAILED`.
39
43
  - **Forgetting the discriminator.** `raw: false` is required on signed swaps; without it TypeScript rejects `walletProvider`.
40
- - **Calling `submitSwapTx` with the full `relayData` object.** The backend expects the `payload: string` field, not the wrapper.
44
+ - **Calling `sodax.api.swaps.submitTx` with the full `relayData` object.** The backend expects the `payload: string` field, not the wrapper.
41
45
 
42
46
  ## Migration workflow (port v1 swap to v2)
43
47
 
@@ -58,7 +62,8 @@ Read in order. Skipping `ai-rules.md` is the most common cause of agents reverti
58
62
  - [`../money-market/SKILL.md`](../money-market/SKILL.md) — if the swap is followed by a supply/borrow action.
59
63
  - [`../partner/SKILL.md`](../partner/SKILL.md) — partner fees on swap.
60
64
  - [`../recovery/SKILL.md`](../recovery/SKILL.md) — stuck-asset recovery for failed swaps.
61
- - [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — `submitSwapTx` and intent / orderbook lookups (step-by-step swap flow + diagnostics).
65
+ - [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — `sodax.api.swaps.submitTx` and intent / orderbook lookups (step-by-step swap flow + diagnostics).
66
+ - [`../swaps-api/SKILL.md`](../swaps-api/SKILL.md) — the typed Swaps API v2 backend client (`sodax.api.swaps`: quote, create-intent, submit-tx, fees) the swap flow calls under the hood.
62
67
 
63
68
  For tasks spanning multiple features, load the broad [`sodax-sdk` skill](../SKILL.md) instead.
64
69