@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
@@ -73,25 +73,21 @@ if (!result.ok) {
73
73
  }
74
74
  ```
75
75
 
76
- ### Custom `IConfigApi` for sandbox
76
+ ### Point tests at a sandbox backend
77
77
 
78
- ```ts
79
- import { Sodax, type IConfigApi } from '@sodax/sdk';
78
+ There is no constructor slot to inject a custom `IConfigApiV1` — the only backend knob is `api` (`ApiConfig = BaseApiConfig | CustomApiConfig`: pass a flat `{ baseURL, timeout?, headers? }`, or a `CustomApiConfig` with separate `baseApiConfig` / `swapsApiConfig` endpoints). To run tests against a sandbox or local mock server, set `api.baseURL` and let `initialize()` fetch config from it:
80
79
 
81
- const sandboxApi: IConfigApi = {
82
- async getChains() { return { ok: true, value: [/* fixture */] }; },
83
- async getSwapTokens() { return { ok: true, value: { /* … */ } }; },
84
- async getSwapTokensByChainId(chainKey) { return { ok: true, value: [/* … */] }; },
85
- async getMoneyMarketTokens() { return { ok: true, value: { /* … */ } }; },
86
- async getMoneyMarketTokensByChainId(chainKey) { return { ok: true, value: [/* … */] }; },
87
- };
80
+ ```ts
81
+ import { Sodax } from '@sodax/sdk';
88
82
 
89
83
  const sodax = new Sodax({
90
- backendApi: { url: 'unused', api: sandboxApi },
84
+ api: { baseURL: 'https://sandbox-api.example.com' },
91
85
  });
92
86
  await sodax.config.initialize();
93
87
  ```
94
88
 
89
+ For fully offline unit tests, stub at the `Sodax` boundary instead (see "Mock the entire `Sodax` instance" above) rather than trying to inject a backend implementation.
90
+
95
91
  ---
96
92
 
97
93
  ## Cross-references
@@ -6,7 +6,7 @@ Lookup tables and inventories. Each file is focused on one domain — token-chea
6
6
  |---|---|
7
7
  | [`chain-keys.md`](chain-keys.md) | All 20 `ChainKeys.*` values × chain family × address-type mapping. Chain-family helper functions. Type aliases (`ChainKey`, `SpokeChainKey`, `EvmChainKey`, `HubChainKey`). |
8
8
  | [`wallet-providers.md`](wallet-providers.md) | `I*WalletProvider` interfaces per chain family. `chainType` discriminant. `GetWalletProviderType<K>`. `IWalletProvider` broad union. Implementation source (consumer's own, or `@sodax/wallet-sdk-core` separate package). |
9
- | [`error-codes.md`](error-codes.md) | The 13 unified `SodaxErrorCode` values + meanings + retry guidance + common context fields. The 8 `SodaxFeature` tags. The `SodaxPhase` orchestration tags. Per-method narrow code unions for every public method on every service. |
9
+ | [`error-codes.md`](error-codes.md) | The 13 unified `SodaxErrorCode` values + meanings + retry guidance + common context fields. The 9 `SodaxFeature` tags (8 domain + `'backend'` for the HTTP-client layer). The `SodaxPhase` orchestration tags. Per-method narrow code unions for every public method on every service. |
10
10
  | [`public-api.md`](public-api.md) | What `@sodax/sdk` barrel exports. Import-rule contract (root-only, no deep imports, types re-exported from `@sodax/types`). |
11
11
  | [`glossary.md`](glossary.md) | Domain terms (hub, spoke, intent, relay, vault, hub-wallet abstraction, etc.) used throughout the docs. |
12
12
 
@@ -1,6 +1,6 @@
1
1
  # Chain keys
2
2
 
3
- 20 supported chains. The `ChainKey` type is the union of every `ChainKeys.*` value. **`SpokeChainKey` is the same union — it includes Sonic.** The "spoke" naming refers to how feature services type their `srcChainKey` parameter (they accept the hub too — bridge / swap / staking etc. all run from Sonic as source via the hub-wallet abstraction). When you specifically need "EVM chains excluding the hub" use `EVM_SPOKE_ONLY_CHAIN_KEYS` / `isEvmSpokeOnlyChainKeyType`.
3
+ 21 supported chains. The `ChainKey` type is the union of every `ChainKeys.*` value. **`SpokeChainKey` is the same union — it includes Sonic.** The "spoke" naming refers to how feature services type their `srcChainKey` parameter (they accept the hub too — bridge / swap / staking etc. all run from Sonic as source via the hub-wallet abstraction). When you specifically need "EVM chains excluding the hub" use `EVM_SPOKE_ONLY_CHAIN_KEYS` / `isEvmSpokeOnlyChainKeyType`.
4
4
 
5
5
  | `ChainKeys.*` | String value | Family | Hub vs spoke | Address type |
6
6
  |---|---|---|---|---|
@@ -16,6 +16,7 @@
16
16
  | `LIGHTLINK_MAINNET` | `'lightlink'` | EVM | spoke | `0x${string}` |
17
17
  | `REDBELLY_MAINNET` | `'redbelly'` | EVM | spoke | `0x${string}` |
18
18
  | `KAIA_MAINNET` | `'0x2019.kaia'` | EVM | spoke | `0x${string}` |
19
+ | `HEDERA_MAINNET` | `'hedera'` | EVM | spoke | `0x${string}` |
19
20
  | `SOLANA_MAINNET` | `'solana'` | SOLANA | spoke | base58 PublicKey string |
20
21
  | `SUI_MAINNET` | `'sui'` | SUI | spoke | `0x${string}` (32-byte) |
21
22
  | `STELLAR_MAINNET` | `'stellar'` | STELLAR | spoke | `G…` |
@@ -35,9 +36,9 @@
35
36
 
36
37
  | Type | What it is |
37
38
  |---|---|
38
- | `ChainKey` | Union of all `ChainKeys.*` values (20 chains). |
39
- | `SpokeChainKey` | `ChainKey` minus `'sonic'` (19 spoke chains). |
40
- | `EvmChainKey` | Subset of `ChainKey` for the 12 EVM chains. |
39
+ | `ChainKey` | Union of all `ChainKeys.*` values (21 chains). |
40
+ | `SpokeChainKey` | Same union as `ChainKey` — includes Sonic (21 chains). For "EVM chains excluding the hub" use `EvmSpokeOnlyChainKey`. |
41
+ | `EvmChainKey` | Subset of `ChainKey` for the 13 EVM chains. |
41
42
  | `HubChainKey` | The literal `'sonic'`. |
42
43
 
43
44
  ### Chain-family helpers
@@ -60,6 +61,41 @@ import {
60
61
 
61
62
  ---
62
63
 
64
+ ## Chain metadata (`baseChainInfo`)
65
+
66
+ `baseChainInfo` (exported from `@sodax/sdk`, re-exported from `@sodax/types`) maps every `ChainKey` to a static `BaseChainInfo` record:
67
+
68
+ | Field | Type | Notes |
69
+ |---|---|---|
70
+ | `name` | `string` | Human-readable chain name. |
71
+ | `key` | `ChainKey` | The chain key (equals the map key). |
72
+ | `chainId` | `string \| number` | Native chain id — number for EVM, string for non-EVM. |
73
+ | `type` | `ChainType` | Chain family — same value as `getChainType(key)`. |
74
+ | `mainnet` | `boolean` | Whether the entry is a mainnet chain. |
75
+ | `logo` | `string` | Default chain logo URL (see below). |
76
+ | `explorer` | `{ baseUrl; txUrl; addressUrl; contractUrl }` | Block-explorer URL templates. |
77
+
78
+ ```ts
79
+ import { baseChainInfo, ChainKeys } from '@sodax/sdk';
80
+
81
+ const { name, logo, explorer } = baseChainInfo[ChainKeys.BASE_MAINNET];
82
+ ```
83
+
84
+ ### Chain logos
85
+
86
+ Each entry's `logo` is a default logo URL — **read `baseChainInfo[key].logo` for chain icons; never hardcode icon paths.** The URL is built from the exported `CHAIN_LOGO_BASE_URL` as `${CHAIN_LOGO_BASE_URL}/${key}.png`:
87
+
88
+ ```ts
89
+ import { baseChainInfo, CHAIN_LOGO_BASE_URL, ChainKeys } from '@sodax/sdk';
90
+
91
+ baseChainInfo[ChainKeys.SONIC_MAINNET].logo;
92
+ // → `${CHAIN_LOGO_BASE_URL}/sonic.png`
93
+ ```
94
+
95
+ The PNGs are hosted in the repo's `@sodax/assets` package and served from `main` via `raw.githubusercontent.com` — so a newly added logo only resolves once merged to `main`. They are not bundled into the SDK.
96
+
97
+ ---
98
+
63
99
 
64
100
  ## Cross-references
65
101
 
@@ -1,9 +1,10 @@
1
1
  # Error codes
2
2
 
3
- All 13 codes the SDK can emit. Each error is `SodaxError<C>` where `C` is one of these. The producing feature is on `error.feature`.
3
+ All 14 codes the SDK can emit. Each error is `SodaxError<C>` where `C` is one of these. The producing feature is on `error.feature`.
4
4
 
5
5
  | Code | Meaning | Common `error.context` fields | Retry advice |
6
6
  |---|---|---|---|
7
+ | `USER_REJECTED` | User cancelled the wallet prompt (signing / approval / connection). Classified at the source by `intentCreationFailed` / `approveFailed` wrappers via a built-in detector that recognises viem `4001` / `UserRejectedRequestError`, ICON Hana `CANCEL_SIGNING` / `-31002`, and name + message patterns from Solana / Sui / Stellar / Stacks / NEAR / Injective wallets. | `phase` (set to whichever phase the wrapper was wrapping: `'intentCreation'` or `'approve'`), `action` | No — user-initiated. Render a "Cancelled" UI, not a failure. |
7
8
  | `VALIDATION_FAILED` | Pre-flight invariant tripped (input shape, unsupported chain, etc.). | `field`, `reason`, `phase: 'validate'` | No — fix the input. |
8
9
  | `INTENT_CREATION_FAILED` | Building the intent / payload failed. | `phase: 'intentCreation'`, `action` | Sometimes — depends on root cause (`error.cause`). |
9
10
  | `EXECUTION_FAILED` | Orchestrator-level catch-all (multi-step op didn't complete). | `action`, `phase: 'execution'` or `'postExecution'` | Sometimes — inspect cause. |
@@ -29,7 +30,9 @@ type SodaxFeature =
29
30
  | 'migration'
30
31
  | 'dex'
31
32
  | 'partner'
32
- | 'recovery';
33
+ | 'recovery'
34
+ | 'backend' // HTTP-client layer (BackendApiService / SwapsApiService) — not a domain feature
35
+ | 'leverageYield';
33
36
  ```
34
37
 
35
38
  The `(feature, code)` pair is the canonical discriminator. Loggers tag both fields; switch statements branch on both.
@@ -75,10 +78,10 @@ Narrow code unions per public method. Use these for exhaustive `switch` discrimi
75
78
 
76
79
  ```ts
77
80
  // 'create*Intent' methods
78
- type CreateIntentErrorCode = 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN';
81
+ type CreateIntentErrorCode = 'USER_REJECTED' | 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN';
79
82
 
80
83
  // 'approve' methods
81
- type ApproveErrorCode = 'VALIDATION_FAILED' | 'APPROVE_FAILED' | 'UNKNOWN';
84
+ type ApproveErrorCode = 'USER_REJECTED' | 'VALIDATION_FAILED' | 'APPROVE_FAILED' | 'UNKNOWN';
82
85
 
83
86
  // 'isAllowanceValid' methods
84
87
  type AllowanceCheckErrorCode = 'VALIDATION_FAILED' | 'ALLOWANCE_CHECK_FAILED' | 'UNKNOWN';
@@ -95,7 +98,7 @@ type LookupErrorCode = 'VALIDATION_FAILED' | 'LOOKUP_FAILED' | 'UNKNOWN';
95
98
  | Method | Narrow code union |
96
99
  |---|---|
97
100
  | `createIntent` | `CreateIntentErrorCode` |
98
- | `swap` | All of {`VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `EXECUTION_FAILED`, `TX_VERIFICATION_FAILED`, `TX_SUBMIT_FAILED`, `RELAY_TIMEOUT`, `RELAY_FAILED`, `EXTERNAL_API_ERROR`, `UNKNOWN`} |
101
+ | `swap` | All of {`USER_REJECTED`, `VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `EXECUTION_FAILED`, `TX_VERIFICATION_FAILED`, `TX_SUBMIT_FAILED`, `RELAY_TIMEOUT`, `RELAY_FAILED`, `EXTERNAL_API_ERROR`, `UNKNOWN`} |
99
102
  | `postExecution` | `EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` (with `phase: 'postExecution'`) |
100
103
  | `createLimitOrder`, `createLimitOrderIntent` | `CreateIntentErrorCode` |
101
104
  | `cancelIntent`, `cancelLimitOrder` | `EXECUTION_FAILED \| VALIDATION_FAILED \| UNKNOWN` |
@@ -104,12 +107,12 @@ type LookupErrorCode = 'VALIDATION_FAILED' | 'LOOKUP_FAILED' | 'UNKNOWN';
104
107
 
105
108
  | Method | Narrow code union |
106
109
  |---|---|
107
- | `supply`, `borrow`, `withdraw`, `repay` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| EXECUTION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| UNKNOWN` (with `action` discriminator) |
110
+ | `supply`, `borrow`, `withdraw`, `repay` | `USER_REJECTED \| VALIDATION_FAILED \| INTENT_CREATION_FAILED \| EXECUTION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| UNKNOWN` (with `action` discriminator) |
108
111
  | `createSupplyIntent`, `createBorrowIntent`, `createWithdrawIntent`, `createRepayIntent` | `CreateIntentErrorCode` |
109
112
  | `approve` | `ApproveErrorCode` |
110
113
  | `isAllowanceValid` | `AllowanceCheckErrorCode` |
111
114
  | `estimateGas` | `GasEstimationErrorCode` |
112
- | Read-only methods (reserves, user data, etc.) | `LookupErrorCode` |
115
+ | Read methods (`sodax.moneyMarket.data.*` — reserves, user data, aToken balances) | throw on failure (bare `Promise<T>`, **not** a `Result`) — wrap in try/catch |
113
116
 
114
117
  ### Staking (`feature: 'staking'`)
115
118
 
@@ -150,11 +153,31 @@ type LookupErrorCode = 'VALIDATION_FAILED' | 'LOOKUP_FAILED' | 'UNKNOWN';
150
153
  | `createXxxIntent` (4 of these) | `CreateIntentErrorCode` |
151
154
  | `approve` | `ApproveErrorCode` |
152
155
  | `isAllowanceValid` | `AllowanceCheckErrorCode` |
153
- | `getAvailableAmount` | `LookupErrorCode` |
156
+
157
+ > `getAvailableAmount` is **not** a public `MigrationService` method — it's an internal `icxMigration` sub-service helper, so it carries no public narrow code union.
154
158
 
155
159
  ### Partner (`feature: 'partner'`) and Recovery (`feature: 'recovery'`)
156
160
 
157
- Both follow the same shape: action methods get the full exec union (`'EXECUTION_FAILED' \| 'INTENT_CREATION_FAILED' \| ...`), read methods get `LookupErrorCode`, approve methods get `ApproveErrorCode`.
161
+ Both follow the same shape: action methods get the full exec union (`'EXECUTION_FAILED' \| 'INTENT_CREATION_FAILED' \| ...`), read methods get `LookupErrorCode`, approve methods get `ApproveErrorCode` (so partner's `approve` can emit `'USER_REJECTED'`).
162
+
163
+ ### Backend / Swaps API (`feature: 'backend'`)
164
+
165
+ `BackendApiService` (`sodax.backendApi`) and the Swaps API v2 client (`sodax.api.swaps`) are the HTTP-client layer — not domain features. Every method returns `Result<T, SodaxError<'EXTERNAL_API_ERROR'>>` with `context.endpoint`, and the transport failure (timeout / non-2xx / response-shape mismatch) preserved on `error.cause`. `context.api` distinguishes the two clients: `'backend'` for `BackendApiService`, `'swaps'` for the `sodax.api.swaps` client.
166
+
167
+ ### Leverage Yield (`feature: 'leverageYield'`)
168
+
169
+ Action discriminator on `context.action`: `'deposit' \| 'withdraw' \| 'approve' \| 'allowanceCheck' \| 'vaultSwap'`.
170
+
171
+ | Method | Narrow code union |
172
+ |---|---|
173
+ | `deposit`, `withdraw`, `createVaultIntent` | `CreateIntentErrorCode` (create-intent subset) |
174
+ | `vaultSwap` | All exec codes: `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` |
175
+ | `notifySolver` | `EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` (with `phase: 'postExecution'`) |
176
+ | `approve` | `ApproveErrorCode` |
177
+ | `isAllowanceValid` | `AllowanceCheckErrorCode` (action `'allowanceCheck'`) |
178
+ | `getApr`, `getEffectiveApr`, `getLsdApr`, `getPosition`, `getTotalAssets`, `previewDeposit`, `previewWithdraw`, `previewRedeem`, `getMaxWithdraw`, `getMaxWithdrawForUser`, `getShareBalance`, `getShareBalanceForUser`, `getAsset` | `LookupErrorCode` (with `method` discriminator) |
179
+
180
+ Relay/tx-verification codes appear only on `vaultSwap`; `createVaultIntent` stays within the create-intent subset. `notifySolver` is public (manual create→relay→notify) and emits the post-execution subset.
158
181
 
159
182
  ---
160
183
 
@@ -17,8 +17,8 @@
17
17
  | **Hub wallet abstraction** | A user-specific contract on the hub that holds funds during cross-chain ops. Resolved via `EvmHubProvider.getUserHubWalletAddress(...)`. |
18
18
  | **`Result<T>`** | The `{ ok: true; value: T } \| { ok: false; error: E }` discriminated union returned by every async public method. |
19
19
  | **`SodaxError<C>`** | The canonical error class. Discriminated by `(feature, code)`. |
20
- | **Code (`SodaxErrorCode`)** | One of 13 reason-only error codes. See § 3. |
21
- | **Feature (`SodaxFeature`)** | One of 8 producing features (`'swap'`, `'moneyMarket'`, …). |
20
+ | **Code (`SodaxErrorCode`)** | One of 14 reason-only error codes. See § 3. |
21
+ | **Feature (`SodaxFeature`)** | One of 9 domain features (`'swap'`, `'moneyMarket'`, …, `'leverageYield'`) plus `'backend'` for the HTTP-client layer (`BackendApiService` / `sodax.api.swaps`). |
22
22
  | **Phase (`SodaxPhase`)** | The orchestration step at which an error occurred. See § 3. |
23
23
  | **Action (`error.context.action`)** | The user-facing operation that triggered the error (`'supply'`, `'stake'`, `'migrateBaln'`, …). |
24
24
  | **`raw: true / false`** | The discriminator on `WalletProviderSlot<K, Raw>`. `true` = build unsigned tx; `false` = sign and broadcast. |
@@ -2,21 +2,35 @@
2
2
 
3
3
  Import everything from `@sodax/sdk`. The barrel re-exports the entire `@sodax/types` surface — you don't need a separate `@sodax/types` dependency.
4
4
 
5
+ `sodax.api` is an alias for `sodax.backendApi`; `sodax.api.swaps` is the typed Swaps API v2 client (`SwapsApiService`) — see [`../features/swaps-api.md`](../features/swaps-api.md).
6
+
5
7
  ### Top-level exports
6
8
 
7
9
  ```ts
8
10
  import {
9
11
  // Main entry
10
12
  Sodax,
11
- type SodaxConfig,
13
+ type SodaxOptions, // constructor param: DeepPartial<SodaxDefaultConfig> & client options (logger + global fee)
14
+ type SodaxConfig, // merged result: SodaxDefaultConfig & client options (e.g. sodax.instanceConfig)
15
+ type SodaxDefaultConfig, // static data contract the backend serves / defaults are built from
12
16
  type DeepPartial,
13
17
 
18
+ // Logging (see recipes/logging.md)
19
+ type SodaxLogger,
20
+ type SodaxLoggerOption,
21
+ consoleLogger,
22
+ silentLogger,
23
+ resolveLogger,
24
+
14
25
  // Chain keys + narrowing
15
26
  ChainKeys,
16
27
  type ChainKey,
17
28
  type SpokeChainKey,
18
29
  type HubChainKey,
19
30
  type EvmChainKey,
31
+ baseChainInfo, // per-chain static metadata (name, key, logo, explorer, …)
32
+ type BaseChainInfo,
33
+ CHAIN_LOGO_BASE_URL, // base URL for default chain logos — baseChainInfo[key].logo
20
34
  getChainType,
21
35
  isEvmChainKeyType,
22
36
  isSolanaChainKeyType,
@@ -59,6 +73,7 @@ import {
59
73
  dexInvariant,
60
74
  partnerInvariant,
61
75
  recoveryInvariant,
76
+ leverageYieldInvariant,
62
77
  mapRelayFailure,
63
78
 
64
79
  // Tokens
@@ -100,17 +115,35 @@ import {
100
115
  type ClClaimRewardsParams,
101
116
  type MigrationParams,
102
117
  type UnifiedBnUSDMigrateParams,
118
+ type LeverageYieldSwapDepositParams,
119
+ type LeverageYieldSwapWithdrawParams,
120
+ type LeverageYieldSwapPayload,
121
+ type VaultSwapActionParams,
122
+ type VaultSwapResponse,
123
+ type CreateVaultIntentResult,
124
+ type LeverageYieldApr,
125
+ type LeverageYieldEffectiveApr,
126
+ type LeverageYieldLsdApr,
127
+ type LeverageYieldPosition,
128
+ type LeverageYieldVault,
103
129
  // …
104
130
 
105
131
  // Backend / relay
106
- type IConfigApi,
107
- type SubmitSwapTxRequest,
108
- type SubmitSwapTxResponse,
132
+ type IConfigApiV1,
133
+ type SubmitTxRequestV2, // swaps API submit-tx request (sodax.api.swaps.submitTx)
134
+ type SubmitTxResponseV2, // swaps API submit-tx response
109
135
  relayTxAndWaitPacket, // function — runs spoke→hub relay submit + wait
110
136
  submitTransaction, // function — relay submit ack only
111
137
  type RelayExtraData,
112
138
  type IntentRelayChainId,
113
139
 
140
+ // Backend API config + per-call override
141
+ type ApiConfig, // BaseApiConfig | CustomApiConfig
142
+ type BaseApiConfig,
143
+ type CustomApiConfig, // point the swaps API at its own endpoint
144
+ type SwapsApiConfig,
145
+ type RequestOverrideConfig, // per-call override on any backendApi / sodax.api.swaps method
146
+
114
147
  // Read shapes
115
148
  type Intent,
116
149
  type IntentResponse,
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: sodax-sdk-leverage-yield
3
+ description: 'Granular skill for the @sodax/sdk v2 leverage-yield feature only — leveraged-yield ERC-4626 vaults on Sonic via LeverageYieldService. Deposit any token → lsoda* shares, withdraw shares → any token (both as solver-tradeable intent swaps), createVaultIntent/vaultSwap/notifySolver, Sonic-direct approve/isAllowanceValid, and reads (getApr, getEffectiveApr, getPosition, getTotalAssets, preview*, getMaxWithdraw*, getShareBalance*, listVaults). Use when the task is leverage-yield vaults (e.g. "deposit into a leverage vault", "withdraw lsoda shares", "vault APR / effective APR", "leverage vault position / health factor", "lsoda share balance"). New in v2 — integration only, no v1 migration path. Links into the parent sodax-sdk knowledge tree. For React dapps, prefer sodax-dapp-kit.'
4
+ license: MIT
5
+ metadata:
6
+ version: '0.0.1'
7
+ author: sodax
8
+ ---
9
+
10
+ # Leverage Yield (Core SDK granular skill)
11
+
12
+ Granular skill for `LeverageYieldService` — `sodax.leverageYield`. Feature tag: `'leverageYield'`. **New in v2; no v1 migration path.**
13
+
14
+ ## Step 1 — Clarify with user before coding
15
+
16
+ 1. **Deposit or withdraw?** Deposit = any spoke token → `lsoda*` shares (delivered to the user's hub wallet). Withdraw = `lsoda*` shares (in the hub wallet) → any token on any chain.
17
+ 2. **Build vs execute.** `deposit` / `withdraw` only *build* a `LeverageYieldSwapPayload`; `vaultSwap` *executes* it end-to-end. Spread the built payload into `vaultSwap({ ...payload, walletProvider })`.
18
+ 3. **End-to-end or manual relay?** `vaultSwap` does create → verify → relay → notify. For backend submit-tx, use `createVaultIntent` then relay yourself and finish with the public `notifySolver`.
19
+ 4. **Reads?** `getEffectiveApr` (headline, AAVE + LSD), `getApr` (AAVE-only — can be negative), `getPosition`, `getTotalAssets`, `previewRedeem`, `getMaxWithdrawForUser` / `getShareBalanceForUser` (resolve the hub wallet from a spoke address internally).
20
+
21
+ ## Integration workflow
22
+
23
+ 1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
24
+ 2. [`../integration/knowledge/features/leverage-yield.md`](../integration/knowledge/features/leverage-yield.md) — `LeverageYieldService` API, the share-as-token model, deposit/withdraw/vaultSwap flows, APR math.
25
+ 3. Path-specific recipe:
26
+ - Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
27
+ - Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
28
+ 4. Errors (`feature: 'leverageYield'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
29
+
30
+ ### Leverage-yield-specific anti-patterns
31
+
32
+ - **Expecting `deposit` / `withdraw` to broadcast.** They are builders returning a `LeverageYieldSwapPayload`. Execute via `vaultSwap({ ...payload, walletProvider })`.
33
+ - **Using `getApr` as the headline number.** For LSD-backed vaults the AAVE-only spread is often negative; `getEffectiveApr` folds in the LSD staking yield (the real source of return).
34
+ - **Passing a spoke address to `getShareBalance` / `getMaxWithdraw`.** Those take a hub address. Use the `*ForUser(vault, srcChainKey, srcAddress)` variants to resolve the hub wallet first.
35
+ - **Gating withdraw on `approve` / `isAllowanceValid`.** Those are Sonic-direct allowance helpers for the vault's underlying asset; the swap-style withdraw authorises the share spend via a hub-wallet `Connection.sendMessage` (`hubWalletSwap: true`).
36
+ - **Quoting on the pre-fee amount.** A deposit's per-intent `partnerFee` is deducted from `inputAmount` before the swap — quote (via the swap solver, `token_dst` = vault) on the post-fee amount.
37
+
38
+ ## Verification
39
+
40
+ 1. `pnpm tsc --noEmit` clean.
41
+ 2. Every `await sodax.leverageYield.<method>(...)` has `if (!result.ok)`.
42
+ 3. Deposit/withdraw build a payload that is then run through `vaultSwap` (or `createVaultIntent` + relay + `notifySolver`).
43
+ 4. APR display uses `getEffectiveApr`; share/withdraw sizing from a spoke address uses the `*ForUser` reads.
44
+
45
+ ## Related granular skills (same family)
46
+
47
+ - [`../swap/SKILL.md`](../swap/SKILL.md) — `vaultSwap` is a leverage-yield copy of the swap intent flow; quote `minOutputAmount` via the solver quote there.
48
+ - [`../recovery/SKILL.md`](../recovery/SKILL.md) — recover stuck hub-wallet assets (including `lsoda*` shares) back to a spoke chain.
49
+
50
+ For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
@@ -1,6 +1,10 @@
1
1
  ---
2
2
  name: sodax-sdk-migration
3
3
  description: 'Granular skill for the @sodax/sdk v2 token-migration feature only — `MigrationService` (`sodax.migration`) covering ICX ↔ SODA, legacy bnUSD ↔ new bnUSD, and BALN → SODA with lockup multipliers. Use when the task is migrating legacy ICON-ecosystem tokens to SODAX (e.g. "migrate ICX to SODA", "revert SODA back to ICX", "swap legacy bnUSD on Sui/Stellar/ICON to new bnUSD", "migrate BALN with lock period for reward multiplier", "claim staked BALN"). IMPORTANT — this is NOT the same as v1 → v2 SDK migration (porting old SDK code). That is a separate cross-cutting concern handled by the broad sodax-sdk skill in migration mode and the migration-v1-to-v2/ knowledge subtree. Same word, different concept. 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
  # Token migration (Core SDK granular skill)
@@ -42,7 +46,7 @@ Only continue here if the task involves one of the three legacy-token sources be
42
46
 
43
47
  - **Assuming `BalnSwapService.stake/unstake/claim/...` return `Result<T>`.** They still THROW — deliberate tech debt. Wrap them in `try/catch` until cleaned up.
44
48
  - **Using `migration` (the SDK module) and `migration-v1-to-v2` (the SDK port) interchangeably.** Different concerns; reading one playbook for the other will produce broken code.
45
- - **Skipping `getAvailableAmount` for partial ICX migrations.** Tells you how much SODA the user can claim from a partial migration.
49
+ - **Misreading `getAvailableAmount`.** It lives on `sodax.migration.icxMigration`, takes **no arguments**, and reads the migration contract's **total available SODA liquidity** on the hub — it is not a per-user "claimable from a partial migration" amount.
46
50
 
47
51
  ## Migration workflow (v1 → v2 of the SDK itself)
48
52
 
@@ -41,7 +41,7 @@ Same word, different concept across versions. Skim before reading the breaking-c
41
41
  | **config** | A `SodaxConfig` object passed at construction with hard-coded chain/token tables. Solver endpoints lived under `SodaxConfig.swaps`. | A `Sodax` instance owns a `ConfigService` that loads from the backend API, with packaged defaults as fallback. `sodax.config.*` is the lookup surface. **Solver endpoints moved to `SodaxConfig.solver`** (not `swaps`); `swaps` is `SwapsConfig` (supported tokens). |
42
42
  | **`xChainId` field on tokens** | Field name on the `Token` type. | Renamed: `XToken.chainKey`. Type also renamed: `Token` → `XToken`. |
43
43
  | **`hubAssets` / `moneyMarketSupportedTokens`** | Static `Record` global maps imported and walked. | `hubAssets` **deleted** — won't compile. `moneyMarketSupportedTokens` **still exported** as a packaged default, but prefer `sodax.config.*` and `sodax.moneyMarket.getSupportedTokens*()` so backend updates take effect. Each `XToken` now carries `vault` and `hubAsset` directly. |
44
- | **`SubmitSwapTxRequest.srcChainId`** | Numeric chain id field on the backend submit-swap request. | Renamed: `srcChainKey: SpokeChainKey`. |
44
+ | **`SubmitSwapTxRequest.srcChainId`** | Numeric chain id field on the v1 backend submit-swap request. | `srcChainKey` on `SubmitTxRequestV2`; submit-tx also moved to `sodax.api.swaps.submitTx`. |
45
45
  | **`Intent.srcChain` / `Intent.dstChain`** | Read shape: `IntentRelayChainId` (bigint). | **Unchanged.** This is the relay chain id, not a spoke chain key. A blanket grep-replace `srcChain`→`srcChainKey` will break this. |
46
46
  | **`AddressType`** | Bitcoin-specific address-type union. | Renamed: `BtcAddressType`. (Generic name freed up.) |
47
47
 
@@ -33,7 +33,7 @@ DO / DO NOT / workflow / stop conditions for AI agents porting v1 `@sodax/sdk` c
33
33
 
34
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
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.
39
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.
@@ -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.
@@ -6,72 +6,72 @@ Pair: [`features/backend-api.md`](../../../integration/knowledge/features/backen
6
6
 
7
7
  ## TL;DR
8
8
 
9
- 1. **Every method now returns `Promise<Result<T>>`** (v1 returned plain `Promise<T>` and threw on failure). `IConfigApi` implementations must update method signatures.
10
- 2. **`SubmitSwapTxRequest.srcChainId` → `srcChainKey`.** And `relayData` field is `string` (`relayData.payload`), not the `RelayExtraData` object. (Cross-cutting detail; covered in detail in [`swap.md`](swap.md).)
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
11
 
12
12
  ## Type / symbol cheat sheet
13
13
 
14
14
  | Method | v1 return | v2 return |
15
15
  |---|---|---|
16
- | `submitSwapTx` | `Promise<SubmitSwapTxResponse>` | `Promise<Result<SubmitSwapTxResponse>>` |
16
+ | `submitSwapTx` → `sodax.api.swaps.submitTx` | `Promise<SubmitSwapTxResponse>` | `Promise<Result<SubmitTxResponseV2>>` |
17
17
  | `getIntentByHash` | `Promise<IntentResponse>` | `Promise<Result<IntentResponse>>` |
18
18
  | `getIntentByTxHash` | (n/a in v1) | `Promise<Result<IntentResponse>>` (v2-new) |
19
- | `getOrderbook` (was `getSolverOrderbook`) | `Promise<OrderbookEntry[]>` | `Promise<Result<OrderbookEntry[]>>` |
20
- | `getUserIntents` (was `getUserSwapHistory`) | `Promise<IntentResponse[]>` | `Promise<Result<IntentResponse[]>>` |
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
21
  | `getChains` | `Promise<ChainConfig[]>` | `Promise<Result<GetChainsApiResponse>>` |
22
22
  | `getSwapTokens` | `Promise<SwapTokenConfig>` | `Promise<Result<GetSwapTokensApiResponse>>` |
23
23
  | `getSwapTokensByChainId` | `Promise<XToken[]>` | `Promise<Result<XToken[]>>` |
24
24
  | `getMoneyMarketTokens` | `Promise<MMTokenConfig>` | `Promise<Result<GetMoneyMarketTokensApiResponse>>` |
25
25
  | `getMoneyMarketTokensByChainId` | `Promise<XToken[]>` | `Promise<Result<XToken[]>>` |
26
- | `SubmitSwapTxRequest.srcChainId` | numeric chain id | renamed → `srcChainKey: SpokeChainKey` |
27
- | `SubmitSwapTxRequest.relayData` | `RelayExtraData` object | now `string` (use `relayData.payload`) |
26
+ | `srcChainId` → `srcChainKey` (`SubmitTxRequestV2`) | numeric chain id | `srcChainKey` (spoke chain key string) |
27
+ | `relayData` (`SubmitTxRequestV2`) | `RelayExtraData` object | now `string` (use `relayData.payload`) |
28
28
 
29
29
  ## Per-method delta
30
30
 
31
31
  ```diff
32
32
  - const response: SubmitSwapTxResponse = await sodax.backendApi.submitSwapTx(request);
33
33
  - // throws on failure
34
- + const result = await sodax.backendApi.submitSwapTx({
34
+ + const result = await sodax.api.swaps.submitTx({ // moved off BackendApiService
35
35
  + txHash: spokeTxHash as string,
36
36
  + srcChainKey: src.chain, // was: srcChainId
37
37
  + walletAddress: '0x…',
38
- + intent: swapIntentData,
38
+ + intent, // IntentRequestV2 (was: SwapIntentData)
39
39
  + relayData: relayData.payload, // was: relayData (object)
40
40
  + });
41
41
  + if (!result.ok) {
42
- + // result.error: SodaxError with feature: 'swap', context.api: 'backend'
42
+ + // result.error: SodaxError with feature: 'backend', context.api: 'swaps'
43
43
  + return;
44
44
  + }
45
- + const response = result.value;
45
+ + const response = result.value; // SubmitTxResponseV2
46
46
  ```
47
47
 
48
- ## Custom `IConfigApi` (sandbox / test fixtures)
48
+ ## Custom `IConfigApiV1` (sandbox / test fixtures)
49
49
 
50
- If you implemented `IConfigApi` for a sandbox or test fixture, two things changed in v2:
50
+ If you implemented `IConfigApiV1` for a sandbox or test fixture, two things changed in v2:
51
51
 
52
52
  **1. Method signatures.** Every method now returns `Promise<Result<T>>` instead of throwing on failure:
53
53
 
54
54
  ```diff
55
- const sandboxApi: IConfigApi = {
55
+ const sandboxApi: IConfigApiV1 = {
56
56
  - async getChains(): Promise<ChainConfig[]> {
57
57
  - return [/* fixture */];
58
58
  - },
59
59
  - async getSwapTokens(): Promise<SwapTokenConfig> { /* … */ },
60
- + async getChains(): Promise<Result<ChainConfig[], unknown>> {
61
- + return { ok: true, value: [/* fixture */] };
60
+ + async getChains(): Promise<Result<readonly SpokeChainKey[]>> {
61
+ + return { ok: true, value: [/* fixture: chain KEYS, not configs */] };
62
62
  + },
63
- + async getSwapTokens(): Promise<Result<SwapTokenConfig, unknown>> { /* … */ },
63
+ + async getSwapTokens(): Promise<Result<Record<SpokeChainKey, readonly XToken[]>>> { /* … */ },
64
64
  // …5 methods total
65
65
  };
66
66
  ```
67
67
 
68
- **2. Injection mechanism.** `SodaxConfig` does NOT expose a typed slot to inject a custom `IConfigApi` 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.
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
69
 
70
70
  ## Pitfalls
71
71
 
72
- 1. **`SubmitSwapTxRequest.relayData` is `string`, not the `RelayExtraData` object.** v1 took the object; v2 takes the `payload` field as a string.
73
- 2. **Backend errors carry `error.context.api === 'backend'`** but the `feature` reflects the call site (`'swap'` for `submitSwapTx`, `'moneyMarket'` for MM-related backend calls, etc.). Use both for logger tag pairs.
74
- 3. **Custom `IConfigApi` implementations must return `Result<T>`** — old throw-on-error implementations will compile-error against the v2 interface.
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
75
 
76
76
  ## Verification
77
77
 
@@ -85,8 +85,8 @@ grep -rE "srcChainId:\s*\w+|\.relayData(?!\s*\.payload)" src/ # legacy field n
85
85
  ## Cross-references
86
86
 
87
87
  - v2 backend API usage: [`features/backend-api.md`](../../../integration/knowledge/features/backend-api.md).
88
- - `submitSwapTx` flow with `createIntent` upstream: [`./swap.md`](swap.md) (the swap migration covers the request-shape changes in detail).
88
+ - submit-tx flow with `createIntent` upstream: [`./swap.md`](swap.md) (the swap migration covers the request-shape changes in detail).
89
89
  - Partner migration (separate service): [`./partner.md`](partner.md).
90
90
  - Recovery migration (separate service, new in v2): [`./recovery.md`](recovery.md).
91
91
  - Result/error model: [`../breaking-changes/result-and-errors.md`](../breaking-changes/result-and-errors.md).
92
- - `IConfigApi` Result-wrapping cross-cutting note: [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 6.
92
+ - `IConfigApiV1` Result-wrapping cross-cutting note: [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 6.