@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
@@ -4,7 +4,7 @@ Every v2 design concept the SDK rests on, in a single TOC-navigable file. Read e
4
4
 
5
5
  ## Section index
6
6
 
7
- 1. [Hub-and-spoke model](#1-hub-and-spoke-model) — Sonic is the hub; 19 spoke chains route through it.
7
+ 1. [Hub-and-spoke model](#1-hub-and-spoke-model) — Sonic is the hub; 20 spoke chains route through it.
8
8
  2. [`SpokeService` router](#2-spokeservice-router) — single internal dispatcher; no per-chain provider classes.
9
9
  3. [`Sodax` facade and service graph](#3-sodax-facade-and-service-graph) — one instance owns every feature service.
10
10
  4. [`ConfigService`](#4-configservice) — dynamic config from backend with packaged-defaults fallback.
@@ -50,7 +50,7 @@ For most consumers, this whole pipeline is one method call (`sodax.swaps.swap(..
50
50
 
51
51
  ### Supported chains
52
52
 
53
- 20 total. EVM (12): Sonic (hub), Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia. Non-EVM (8): Solana, Sui, Stellar, ICON, Injective, NEAR, Stacks, Bitcoin. See [`reference/`](reference/) § "Chain keys" for the full table with relay IDs and address-type mapping.
53
+ 21 total. EVM (13): Sonic (hub), Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera. Non-EVM (8): Solana, Sui, Stellar, ICON, Injective, NEAR, Stacks, Bitcoin. See [`reference/`](reference/) § "Chain keys" for the full table with relay IDs and address-type mapping.
54
54
 
55
55
  ---
56
56
 
@@ -62,7 +62,7 @@ Instead, the SDK has **one** `SpokeService` instance (owned by `Sodax`) which ho
62
62
 
63
63
  ```
64
64
  SpokeService
65
- ├── EvmSpokeService (handles all 12 EVM chains)
65
+ ├── EvmSpokeService (handles all 13 EVM chains)
66
66
  ├── SonicSpokeService (special-cased for the hub)
67
67
  ├── SolanaSpokeService
68
68
  ├── SuiSpokeService
@@ -95,7 +95,7 @@ The chain key is the bridge between the type system and runtime routing.
95
95
  The `Sodax` class is the public entry point. It constructs and wires every service once at construction time, then reuses them across calls:
96
96
 
97
97
  ```ts
98
- const sodax = new Sodax(/* optional DeepPartial<SodaxConfig> */);
98
+ const sodax = new Sodax(/* optional SodaxOptions */);
99
99
  await sodax.config.initialize(); // fetch dynamic config; fall back to packaged defaults
100
100
 
101
101
  // All feature services accessed off the instance:
@@ -116,7 +116,8 @@ Sodax
116
116
  ├── migration — MigrationService (ICX/bnUSD/BALN migration)
117
117
  ├── partners — PartnerService (partner fee claiming)
118
118
  ├── recovery — RecoveryService (withdraw stuck hub-wallet assets)
119
- ├── backendApi — BackendApiService (intent lookup, swap submission, config fetching)
119
+ ├── backendApi — BackendApiService (intent lookup, orderbook, money-market reads, config fetching)
120
+ ├── api — alias for backendApi; `api.swaps` is SwapsApiService (typed Swaps API v2 client)
120
121
  ├── config — ConfigService (dynamic config; see § 4)
121
122
  ├── hubProvider — HubProvider (hub contract interactions; concrete impl `EvmHubProvider`)
122
123
  └── spoke — SpokeService (per-chain-family router; see § 2)
@@ -127,21 +128,23 @@ All feature services receive `{ hubProvider, config, spoke }` via constructor in
127
128
  ### Constructor
128
129
 
129
130
  ```ts
130
- import { Sodax, type SodaxConfig, type DeepPartial } from '@sodax/sdk';
131
+ import { Sodax, type SodaxOptions } from '@sodax/sdk';
131
132
 
132
- new Sodax(config?: DeepPartial<SodaxConfig>): Sodax;
133
+ new Sodax(config?: SodaxOptions): Sodax;
133
134
  ```
134
135
 
135
- `SodaxConfig` has exactly **10 fields** (all required at the type level, but `DeepPartial` makes every leaf optional):
136
+ `SodaxOptions` is `DeepPartial<SodaxDefaultConfig> & { logger?: SodaxLoggerOption; fee?: PartnerFee }` — a deep-partial override of the `SodaxDefaultConfig` data contract, plus the client-side options (`logger` sink + global partner `fee`) kept off `SodaxDefaultConfig` itself: the integrator sets them, they are resolved once, and the backend never fetches or overwrites them. Read the resolved global fee back via `sodax.config.fee`. The global `fee` is the **default applied to any feature whose own `partnerFee` is unset** — the effective fee is `featureFee ?? fee`, resolved via `sodax.config.swapPartnerFee` / `moneyMarketPartnerFee` / `bridgePartnerFee` / `leverageYieldPartnerFee`. (See [`recipes/logging.md`](recipes/logging.md) for the `logger` precedent.)
136
137
 
137
- - `fee: PartnerFee | undefined` — global partner fee, applied unless a feature-level config overrides.
138
- - `chains: Record<SpokeChainKey, SpokeChainConfig>` — per-spoke-chain config. Each entry carries `rpcUrl`, polling config, and chain-family-specific extras (`BitcoinSpokeChainConfig`, `StellarSpokeChainConfig`, etc.).
139
- - `swaps: SwapsConfig` — supported solver tokens per chain.
140
- - `moneyMarket: MoneyMarketConfig` — money market contracts + supported tokens.
138
+ `SodaxDefaultConfig` has exactly **10 fields** (all required at the type level, but `DeepPartial` makes every leaf optional):
139
+
140
+ - `chains: Record<SpokeChainKey, SpokeChainConfig>` — per-spoke-chain config. Each entry carries `rpcUrl`, polling config, and chain-family-specific extras (`BitcoinSpokeChainConfig`, `StellarSpokeChainConfig`, etc.). EVM hub/Sonic entries also accept an optional `rpcUrls` failover list (see [`recipes/initialize-sodax.md`](recipes/initialize-sodax.md)).
141
+ - `swaps: SwapsConfig` — supported solver tokens per chain (+ optional per-feature `partnerFee` override).
142
+ - `moneyMarket: MoneyMarketConfig` — money market contracts + supported tokens (+ optional per-feature `partnerFee` override).
141
143
  - `bridge: BridgeConfig` — bridge `{ partnerFee }` override.
142
144
  - `dex: DexConfig` — DEX pool/asset config.
143
- - `hub: HubConfig` — hub-chain (Sonic) full address map + RPC URL + polling config.
144
- - `api: ApiConfig` — backend API endpoint (`{ baseURL, timeout, headers }`).
145
+ - `leverageYield: LeverageYieldConfig` — registry of leverage-yield ERC-4626 vaults on the hub.
146
+ - `hub: HubConfig` — hub-chain (Sonic) full address map + RPC URL + polling config. Accepts an optional `rpcUrls` failover list (and `rpcOptions` tuning) — see [`recipes/initialize-sodax.md`](recipes/initialize-sodax.md).
147
+ - `api: ApiConfig` — backend API config: flat `BaseApiConfig` (`{ baseURL, timeout, headers }`, shared by `sodax.backendApi` and the swaps client `sodax.api.swaps`) or nested `CustomApiConfig` (`{ baseApiConfig?, swapsApiConfig? }`) to point the swaps API at its own endpoint.
145
148
  - `solver: SolverConfig` — `{ intentsContract, solverApiEndpoint, protocolIntentsContract }`.
146
149
  - `relay: RelayConfig` — intent relay endpoint + chain-id map.
147
150
 
@@ -188,7 +191,7 @@ const sodax = new Sodax({
188
191
  });
189
192
  ```
190
193
 
191
- `SodaxConfig.api` is `ApiConfig` (`{ baseURL, timeout, headers }`) — pass any subset via `DeepPartial`. v2 does not provide a typed slot to inject a custom `IConfigApi` implementation at construction; if you need to mock the backend for tests, point `baseURL` at a local mock server, or construct your own `BackendApiService`-compatible mock and inject it where you control the `Sodax` instance (e.g. dependency-injected in your app layer).
194
+ `SodaxConfig.api` is `ApiConfig` — the flat `BaseApiConfig` (`{ baseURL, timeout, headers }`) shared by both backend clients, or the nested `CustomApiConfig` (`{ baseApiConfig?, swapsApiConfig? }`) to point the swaps API (`sodax.api.swaps`) at its own endpoint. Pass any subset via `DeepPartial`. v2 does not provide a typed slot to inject a custom `IConfigApiV1` implementation at construction; if you need to mock the backend for tests, point `baseURL` at a local mock server, or construct your own `BackendApiService`-compatible mock and inject it where you control the `Sodax` instance (e.g. dependency-injected in your app layer).
192
195
 
193
196
  ---
194
197
 
@@ -229,7 +232,7 @@ This is what allows `sodax.swaps.createIntent({ params: { srcChainKey: ChainKeys
229
232
  ```ts
230
233
  import { getChainType, isEvmChainKeyType, isSolanaChainKeyType, isBitcoinChainKeyType, /* … */ } from '@sodax/sdk';
231
234
 
232
- getChainType(chainKey); // 'EVM' | 'BITCOIN' | 'SOLANA' | 'STELLAR' | 'SUI' | 'ICON' | 'INJECTIVE' | 'STACKS' | 'NEAR' | 'SONIC'
235
+ getChainType(chainKey); // 'EVM' | 'BITCOIN' | 'SOLANA' | 'STELLAR' | 'SUI' | 'ICON' | 'INJECTIVE' | 'STACKS' | 'NEAR'
233
236
  isEvmChainKeyType(chainKey); // boolean (with type guard)
234
237
  ```
235
238
 
@@ -346,7 +349,7 @@ The canonical error class. Every SDK-emitted error is a `SodaxError<C>` paramete
346
349
  ```ts
347
350
  class SodaxError<C extends SodaxErrorCode = SodaxErrorCode> extends Error {
348
351
  readonly code: C; // closed 13-code reason union
349
- readonly feature: SodaxFeature; // 'swap' | 'moneyMarket' | 'bridge' | 'staking' | 'migration' | 'dex' | 'partner' | 'recovery'
352
+ readonly feature: SodaxFeature; // 'swap' | 'moneyMarket' | 'bridge' | 'staking' | 'migration' | 'dex' | 'partner' | 'recovery' | 'backend' | 'leverageYield'
350
353
  readonly cause?: unknown;
351
354
  readonly context?: SodaxErrorContext;
352
355
 
@@ -382,7 +385,7 @@ Public methods declare narrow code unions via `Extract<SodaxErrorCode, ...>`:
382
385
  ```ts
383
386
  type CreateSupplyIntentErrorCode = Extract<
384
387
  SodaxErrorCode,
385
- 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN'
388
+ 'USER_REJECTED' | 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN'
386
389
  >;
387
390
  ```
388
391
 
@@ -448,8 +451,8 @@ Use these in cross-bundle code (apps with mixed ESM/CJS resolution, monorepos wi
448
451
 
449
452
  Cross-chain coordination is exposed as two top-level functions (re-exported from `@sodax/sdk`'s barrel):
450
453
 
451
- - `submitTransaction({ relayerApiEndpoint, srcChainKey, txHash, payload })` — POSTs the spoke transaction to the relay submit endpoint and resolves the relay's first-stage acknowledgement.
452
- - `relayTxAndWaitPacket({ relayerApiEndpoint, srcChainKey, dstChainKey, txHash, payload, timeout? })` — runs `submitTransaction` and then polls until the destination packet reaches `executed`.
454
+ - `submitTransaction(payload, apiUrl)` — TWO positional args: `payload: IntentRelayRequest<'submit'>` and `apiUrl: HttpUrl` (not an options object). POSTs the spoke transaction to the relay submit endpoint and resolves the relay's first-stage acknowledgement.
455
+ - `relayTxAndWaitPacket({ srcTxHash, data, chainKey, relayerApiEndpoint, timeout, pollTxHash? })` — `RelayAndWaitParams`: `data` is the whole `RelayExtraData` / `OnDemandRelayData` object and `chainKey` is the source `SpokeChainKey`. Runs `submitTransaction` and then polls until the destination packet reaches `executed`.
453
456
 
454
457
  These functions are **not** exposed on the `Sodax` instance. Consumers don't call them directly — every feature service (`swaps.swap`, `bridge.bridge`, `staking.stake`, …) wraps the spoke→hub leg internally. If you genuinely need custom relay orchestration (rare), import `relayTxAndWaitPacket` / `submitTransaction` from `@sodax/sdk` and pass the same `relayerApiEndpoint` your `Sodax` instance uses.
455
458
 
@@ -475,7 +478,7 @@ The single shared mapper from a relay-layer error to a `SodaxError`. Every featu
475
478
  import { mapRelayFailure, relayTxAndWaitPacket } from '@sodax/sdk';
476
479
 
477
480
  try {
478
- await relayTxAndWaitPacket({ /* relayerApiEndpoint, srcChainKey, dstChainKey, txHash, payload, timeout? */ });
481
+ await relayTxAndWaitPacket({ /* srcTxHash, data, chainKey, relayerApiEndpoint, timeout, pollTxHash? */ });
479
482
  } catch (e) {
480
483
  const sodaxError = mapRelayFailure(e, {
481
484
  feature: 'swap',
@@ -1,17 +1,37 @@
1
- # Chain specifics — Non-EVM quirks
1
+ # Chain specifics — chain quirks
2
2
 
3
- EVM chains (12 of them) work uniformly through `IEvmWalletProvider`. Non-EVM chains have particularities you need to handle. This file documents each chain family's quirks.
3
+ EVM chains mostly work uniformly through `IEvmWalletProvider`, with **one** native-value exception (Hedera, below). Non-EVM chains have more particularities you need to handle. This file documents each chain family's quirks.
4
4
 
5
5
  ## Section index
6
6
 
7
+ EVM:
8
+
9
+ 0. [Hedera HBAR msg.value scaling](#0-hedera-hbar-msgvalue-scaling) — `HEDERA_MAINNET`. The only EVM-family quirk: native deposits scale `msg.value` by 10^10. Handled automatically by the SDK.
10
+
11
+ Non-EVM:
12
+
7
13
  1. [Stellar trustline](#1-stellar-trustline) — `STELLAR_MAINNET`. Required before receiving any non-XLM asset.
8
- 2. [Bitcoin PSBT and Radfi](#2-bitcoin-psbt-and-radfi) — `BITCOIN_MAINNET`. PSBT signing; trading wallet; Radfi auth/session.
14
+ 2. [Bitcoin PSBT and Bound Exchange](#2-bitcoin-psbt-and-radfi) — `BITCOIN_MAINNET`. PSBT signing; trading wallet; Bound Exchange auth/session.
9
15
  3. [Solana PDA derivation](#3-solana-pda-derivation) — `SOLANA_MAINNET`. Deterministic addresses; one-time setup utilities.
10
16
  4. [ICON Hana wallet](#4-icon-hana-wallet) — `ICON_MAINNET`. Low-level Hana-extension helpers; chain key string vs numeric ID.
11
17
  5. [NEAR connector discovery](#5-near-connector-discovery) — `NEAR_MAINNET`. Account-id semantics; multiple wallet variants.
12
18
 
13
19
  ---
14
20
 
21
+ ## 0. Hedera HBAR msg.value scaling
22
+
23
+ **Quirk:** HBAR is tracked with **8 decimals** in SODAX spoke accounting, but Hedera's EVM layer treats native `msg.value` as **18 decimals**. So for a native-HBAR deposit the on-chain `msg.value` must be the 8-decimal amount multiplied by **10^10**, even though the asset-manager `transfer` argument stays in 8 decimals.
24
+
25
+ ### How v2 handles it
26
+
27
+ **Nothing to do — it's automatic.** `EvmSpokeService` scales `msg.value` internally when the source chain is `HEDERA_MAINNET` and the deposit is native; every other EVM chain passes the amount through unchanged. You always pass the canonical 8-decimal HBAR amount to the deposit / swap / bridge call, exactly as you would any other chain's native amount — the spoke service applies the 10^10 factor only to the transaction's `value` field.
28
+
29
+ ### Pitfall
30
+
31
+ Do **not** pre-scale the amount yourself. Pass the plain 8-decimal HBAR amount; multiplying by 10^10 before handing it to the SDK double-scales and overpays. The scaling applies only to the native token (HBAR) — HTS / ERC-20 token deposits on Hedera carry `value: 0` and are unaffected.
32
+
33
+ ---
34
+
15
35
  ## 1. Stellar trustline
16
36
 
17
37
  **Requirement:** before a Stellar account can hold or receive a non-XLM asset, it must establish a trustline to the asset issuer. SODAX's bridge / swap / money-market deliver stablecoin assets to Stellar — the destination Stellar account must have an active trustline for the asset, or the operation fails.
@@ -39,7 +59,7 @@ Stellar accounts that have never held the asset have **no** trustline — receiv
39
59
 
40
60
  ---
41
61
 
42
- ## 2. Bitcoin PSBT and Radfi
62
+ ## 2. Bitcoin PSBT and Bound Exchange
43
63
 
44
64
  Bitcoin support uses Partially Signed Bitcoin Transactions (PSBT) — a different model than EVM tx signing. The wallet provider (`BTCWalletProvider`) handles PSBT construction and signing internally.
45
65
 
@@ -51,11 +71,11 @@ type BtcAddressType = 'P2PKH' | 'P2SH' | 'P2WPKH' | 'P2TR';
51
71
 
52
72
  `BTCWalletProvider` config takes an `addressType`. `'P2WPKH'` (native SegWit) is the modern default; `'P2TR'` (Taproot) is supported but may have lower compatibility with some on-chain logic.
53
73
 
54
- ### Radfi (auth + trading wallet)
74
+ ### Bound Exchange (auth + trading wallet)
55
75
 
56
- SODAX uses the Radfi infrastructure for Bitcoin. Each user gets a derived "trading wallet" funded from their main BTC address. Operations consume UTXOs from the trading wallet rather than directly from the user's main address.
76
+ SODAX uses the Bound Exchange infrastructure for Bitcoin. Each user gets a derived "trading wallet" funded from their main BTC address. Operations consume UTXOs from the trading wallet rather than directly from the user's main address.
57
77
 
58
- The Radfi provider is owned by `BitcoinSpokeService`. Reach it via the spoke router:
78
+ The Bound Exchange provider is owned by `BitcoinSpokeService`. Reach it via the spoke router:
59
79
 
60
80
  ```ts
61
81
  import { ChainKeys, type BitcoinSpokeService } from '@sodax/sdk';
@@ -64,10 +84,10 @@ const btcSpoke = sodax.spoke.getSpokeService(ChainKeys.BITCOIN_MAINNET) as Bitco
64
84
  const radfi = btcSpoke.radfi; // RadfiProvider instance
65
85
  ```
66
86
 
67
- Most consumer flows don't need to touch `radfi` directly — `sodax.bridge.bridge(...)`, `sodax.swaps.createIntent(...)`, etc. handle the Radfi auth + trading-wallet routing internally on the Bitcoin path. For explicit lifecycle management:
87
+ Most consumer flows don't need to touch `radfi` directly — `sodax.bridge.bridge(...)`, `sodax.swaps.createIntent(...)`, etc. handle the Bound Exchange auth + trading-wallet routing internally on the Bitcoin path. For explicit lifecycle management:
68
88
 
69
89
  ```ts
70
- // Authenticate against Radfi (the wallet signs an auth message):
90
+ // Authenticate against Bound Exchange (the wallet signs an auth message):
71
91
  await radfi.authenticateWithWallet(/* args per RadfiProvider source */);
72
92
 
73
93
  // Fetch the trading wallet for an address (creating it if needed):
@@ -80,11 +100,13 @@ const balance = await radfi.getBalance(tradingWallet.address);
80
100
  const exists = await radfi.checkIfTradingWalletExists(personalAddress);
81
101
  ```
82
102
 
103
+ **Server-side / raw flows (no interactive sign-in).** A backend that builds raw Bitcoin intents can't run the BIP322 login, so seed a pre-provisioned Bound token instead of authenticating. `RadfiProvider` honors three injection points: `new Sodax({ ... })` with `radfi.accessToken` (and optional `refreshToken`) in the Bitcoin chain config (the constructor seeds them), `radfi.setRadfiAccessToken(token)` at runtime, or a per-action `extras.bound.accessToken` on `createIntent` (the Bitcoin-gated `bound` slot groups Bound/Radfi inputs). If an authenticated Bound call has neither a token nor a configured `apiKey`, `RadfiProvider` throws a legible `RadfiApiError` (the message names the fix: inject via `setRadfiAccessToken` or `new Sodax({ ... })` with `radfi.accessToken`) instead of sending an empty bearer and getting an opaque 403.
104
+
83
105
  Other public methods on `RadfiProvider` you may need: `setRadfiAccessToken`, `refreshAccessToken`, `createTradingWallet`, `createWithdrawTransaction`, `requestRadfiSignature`, `getExpiredUtxos`, `buildRenewUtxoTransaction`, `signAndBroadcastRenewUtxo`, `withdrawToUser`, `signAndBroadcastWithdraw`, `getMaxWithdrawable`. Read `RadfiProvider` source for argument shapes — the API surface is broader than typical chain providers.
84
106
 
85
107
  ### Pitfall
86
108
 
87
- `BitcoinSpokeService.radfi` is what feature services use under the hood. Bypassing the feature services and driving Radfi yourself works but is rarely needed — and you have to wire token balances + UTXO state manually. Prefer the standard feature flows unless you specifically need lifecycle control.
109
+ `BitcoinSpokeService.radfi` is what feature services use under the hood. Bypassing the feature services and driving Bound Exchange yourself works but is rarely needed — and you have to wire token balances + UTXO state manually. Prefer the standard feature flows unless you specifically need lifecycle control.
88
110
 
89
111
  ---
90
112
 
@@ -168,6 +190,31 @@ Both are valid. `GetAddressType<typeof ChainKeys.NEAR_MAINNET>` accepts both via
168
190
 
169
191
  `NearWalletProvider` requires the `accountId` field at construction (alongside `privateKey`). Unlike EVM, NEAR can't derive an account from a key alone — keys are scoped to accounts.
170
192
 
193
+ ### Receiving tokens: NEP-141 storage registration
194
+
195
+ Before a NEAR account can **receive** (hold a balance of) a NEP-141 token, it must pay a one-time storage bond on that token contract — delivering to an unregistered account fails. This gates any flow that delivers a token to a user on NEAR: swap output on NEAR, bridge into NEAR, money-market borrow/withdraw to NEAR. (Native NEAR is not a NEP-141 token and needs no registration.)
196
+
197
+ The NEAR spoke service exposes two methods — reach it via `sodax.spoke.near` or `sodax.spoke.getSpokeService(ChainKeys.NEAR_MAINNET)`:
198
+
199
+ - `isStorageRegistered(token, accountId): Promise<boolean>` — whether `accountId` can already receive `token`. Returns `true` for the native token (no NEP-141). Read-only; uses the configured NEAR RPC.
200
+ - `registerStorage({ token, accountId, walletProvider, deposit?, raw? })` — submits a `storage_deposit` for `accountId`; returns the tx hash (or the unsigned tx when `raw: true`). `deposit` defaults to `NEAR_STORAGE_DEPOSIT` (0.00125 NEAR, exported from `@sodax/sdk`) — override per token if its `storage_balance_bounds.min` differs. Throws for the native token. The recipient's NEAR wallet signs it.
201
+
202
+ Gate pattern, run before delivering to NEAR:
203
+
204
+ ```ts
205
+ // @ai-snippets-skip — illustrative.
206
+ const near = sodax.spoke.near;
207
+ if (!(await near.isStorageRegistered(token, accountId))) {
208
+ await near.registerStorage({ token, accountId, walletProvider });
209
+ }
210
+ ```
211
+
212
+ The `sodax-dapp-kit` skill wraps these as the `useNearStorageCheck` / `useRegisterNearStorage` hooks plus a `resolveNearStorageGate` helper (integration mode).
213
+
214
+ ### `ft_transfer_call` attaches 1 yoctoNEAR
215
+
216
+ Deposits **from** NEAR (`deposit()` / `fillIntent()` on the NEAR spoke service) call the token's `ft_transfer_call`, which per NEP-141 must carry **exactly 1 yoctoNEAR** — the spoke service attaches it automatically. The signer only needs a small NEAR balance to cover gas (the 1 yoctoNEAR is dust). Native-token deposits use a plain `transfer` and aren't subject to this.
217
+
171
218
  ---
172
219
 
173
220
  ## Other non-EVM chains
@@ -9,6 +9,7 @@ One file per feature service. Each file documents the v2 API surface, common cal
9
9
  | [`staking.md`](staking.md) | `StakingService` | SODA → xSoda staking via ERC-4626 vault. Stake, unstake (with penalty curve), instant unstake (slippage), claim, cancel. |
10
10
  | [`bridge.md`](bridge.md) | `BridgeService` | Cross-chain token transfer via vault. `bridge` returns `TxHashPair = { srcChainTxHash, dstChainTxHash }`. Bridgeable-amount queries respect vault deposit limits. |
11
11
  | [`dex.md`](dex.md) | `ClService` + `AssetService` | Uniswap-V3-style concentrated liquidity positions. Asset deposit/withdraw. Increase/decrease/claim flows. |
12
+ | [`leverage-yield.md`](leverage-yield.md) | `LeverageYieldService` | Leveraged-yield ERC-4626 vaults on Sonic. Deposit/withdraw as solver-tradeable `lsoda*` swaps; effective APR (AAVE + LSD), position, share-balance reads. |
12
13
  | [`migration.md`](migration.md) | `MigrationService` (the SDK module — not v1→v2 porting) | Legacy ICON ecosystem token migration. ICX ↔ SODA, legacy bnUSD ↔ new bnUSD, BALN → SODA with lockup multipliers. |
13
14
  | [`partner.md`](partner.md) | `PartnerService` | Partner-fee handling: token approval, auto-swap preferences, fee-claim flows. |
14
15
  | [`recovery.md`](recovery.md) | `RecoveryService` | Withdraw stuck hub-wallet assets back to a spoke chain. |
@@ -18,4 +19,4 @@ All feature services are constructed and wired by the `Sodax` facade. You don't
18
19
 
19
20
  ## Cross-references to migration
20
21
 
21
- For the v1 → v2 port playbook on each feature, see the matching file in [`features/`](../../../migration-v1-to-v2/knowledge/features/) — same filename, different angle.
22
+ For the v1 → v2 port playbook on each feature, see the matching file in [`features/`](../../../migration-v1-to-v2/knowledge/features/) — same filename, different angle. **Exception:** features introduced in v2 with no v1 equivalent (`leverage-yield.md`) have no migration sibling — there is nothing to port.
@@ -1,19 +1,21 @@
1
1
  # Backend API — `BackendApiService`
2
2
 
3
- HTTP client for backend services. Provides intent lookup, swap-tx submission, solver orderbook queries, money-market position/reserve reads, and (internally) config fetching. Most consumer-side code uses just `submitSwapTx`, `getIntentByHash` / `getIntentByTxHash`, and the money-market read methods.
3
+ HTTP client for backend services. Provides intent lookup, solver orderbook queries, money-market position/reserve reads, and (internally) config fetching. Most consumer-side code uses just `getIntentByHash` / `getIntentByTxHash` and the money-market read methods. Swap-tx submission lives on the sibling swaps API client — `sodax.api.swaps.submitTx` (see below).
4
4
 
5
- Access: `sodax.backendApi`. Service class: `BackendApiService`. **Feature tag for errors:** appears under multiple features depending on the call site (`'swap'` for `submitSwapTx`, `'moneyMarket'` for MM-related reads, etc.); errors carry `error.context.api: 'backend'`.
5
+ Access: `sodax.backendApi`. Service class: `BackendApiService`. **Feature tag for errors:** every method emits `feature: 'backend'` with `error.context.api: 'backend'` (the HTTP-client layer — the domain feature tags like `'moneyMarket'` belong to the on-chain services, not these backend reads).
6
6
 
7
7
  ## Methods
8
8
 
9
9
  ```ts
10
- // Swap-related
11
- sodax.backendApi.submitSwapTx(request, config?): Promise<Result<SubmitSwapTxResponse>>;
12
- sodax.backendApi.getSubmitSwapTxStatus(...): Promise<Result<...>>;
13
- sodax.backendApi.getOrderbook(...): Promise<Result<OrderbookEntry[]>>;
10
+ // Swap-related reads
11
+ sodax.backendApi.getOrderbook(...): Promise<Result<OrderbookResponse>>; // object: { total: number; data: Array<{ intentState, intentData }> } — NOT an array
14
12
  sodax.backendApi.getIntentByHash(intentHash, config?): Promise<Result<IntentResponse>>;
15
13
  sodax.backendApi.getIntentByTxHash(txHash, config?): Promise<Result<IntentResponse>>;
16
- sodax.backendApi.getUserIntents(...): Promise<Result<IntentResponse[]>>;
14
+ sodax.backendApi.getUserIntents(...): Promise<Result<UserIntentsResponse>>; // { total, offset, limit, items: IntentResponse[] } — intents under .items
15
+
16
+ // Swap-tx submission — on the swaps API client (sodax.api.swaps), not BackendApiService
17
+ sodax.api.swaps.submitTx(request, config?): Promise<Result<SubmitTxResponseV2>>;
18
+ sodax.api.swaps.getSubmitTxStatus(query, config?): Promise<Result<SubmitTxStatusResponseV2>>;
17
19
 
18
20
  // Money-market reads (these are the canonical reads for MM positions/reserves;
19
21
  // MoneyMarketService does NOT expose getReservesData / getUserReservesData / etc.)
@@ -24,7 +26,7 @@ sodax.backendApi.getMoneyMarketAssetBorrowers(...): Promise<Result<...>>;
24
26
  sodax.backendApi.getMoneyMarketAssetSuppliers(...): Promise<Result<...>>;
25
27
  sodax.backendApi.getAllMoneyMarketBorrowers(...): Promise<Result<...>>;
26
28
 
27
- // Config-API methods (used internally by ConfigService — implements `IConfigApi`)
29
+ // Config-API methods (used internally by ConfigService — implements `IConfigApiV1`)
28
30
  sodax.backendApi.getAllConfig(config?): Promise<Result<GetAllConfigApiResponse>>;
29
31
  sodax.backendApi.getChains(config?): Promise<Result<GetChainsApiResponse>>;
30
32
  sodax.backendApi.getSwapTokens(config?): Promise<Result<GetSwapTokensApiResponse>>;
@@ -35,27 +37,35 @@ sodax.backendApi.getMoneyMarketTokensByChainId(...): Promise<Result<XToken[]>>;
35
37
  sodax.backendApi.getRelayChainIdMap(config?): Promise<Result<GetRelayChainIdMapApiResponse>>;
36
38
  ```
37
39
 
38
- All methods return `Result<T, SodaxError>` where the error carries `feature: 'swap' | 'moneyMarket' | …` (depending on call site) and `error.context.api === 'backend'`.
40
+ All methods return `Result<T, SodaxError<'EXTERNAL_API_ERROR'>>` where the error carries `feature: 'backend'`, `error.context.api === 'backend'`, and `context.endpoint`.
41
+
42
+ Every data / token / money-market response is validated at runtime against a valibot schema (like `sodax.api.swaps`): a 2xx body that fails the contract resolves to `EXTERNAL_API_ERROR` with `context.reason: 'invalid_response_shape'` rather than a mistyped value. The config/relay reads — `getAllConfig`, `getSpokeChainConfig`, `getRelayChainIdMap` — are **not** schema-validated (the `SodaxConfig` shape is too large to mirror faithfully, and `ConfigService` already version-gates and falls back to packaged defaults, so it relies on no response-shape guarantee).
39
43
 
40
- ## Common call shape — `submitSwapTx`
44
+ ## Common call shape — submit swap tx (`sodax.api.swaps.submitTx`)
41
45
 
42
46
  After `sodax.swaps.createIntent({ params, raw: false, walletProvider })` returns:
43
47
 
44
48
  ```ts
45
- const submitResult = await sodax.backendApi.submitSwapTx({
49
+ const submitResult = await sodax.api.swaps.submitTx({
46
50
  txHash: spokeTxHash as string,
47
51
  srcChainKey: src.chain,
48
52
  walletAddress: '0x…',
49
- intent: swapIntentData,
53
+ intent, // IntentRequestV2 (bigint fields) — the createIntent intent passes through
50
54
  relayData: relayData.payload, // string, not the RelayExtraData object
51
55
  });
52
56
 
53
57
  if (!submitResult.ok) return;
54
58
  ```
55
59
 
60
+ ## Swap-intent request DTO — `bound.accessToken` (Bitcoin TRADING)
61
+
62
+ `CreateIntentParamsV2` is the shared wire-level request body behind the typed `/swaps/allowance/check`, `/swaps/approve`, and `/swaps/intents` calls (the `IBackendApiV2` methods the SDK drives internally). It inherits the swap extras — `partnerFee`, `srcPublicKey`, and `bound` — from `SwapExtrasV2`, the JSON-safe mirror of the SDK `SwapExtras` (`QuoteRequestV2` inherits the same trio for its `includeTxData=true` path). For Bitcoin **TRADING**-mode `raw` intents the Bound Exchange (Radfi) token is carried as `bound.accessToken` — passed in the request body instead of an `x-bound-access-token` header so it stays inside the typed DTO. Required only when the source chain is Bitcoin in TRADING mode; ignored otherwise.
63
+
64
+ You rarely build this DTO yourself: `sodax.swaps.createIntent` takes the token via the chain-key-gated `extras.bound.accessToken` slot and maps it onto `CreateIntentParamsV2.bound.accessToken`. See [`swap.md`](swap.md) § `SwapExtras` and [`../chain-specifics.md`](../chain-specifics.md) § "Bitcoin PSBT and Bound Exchange" for the consumer-facing flow and token-injection points.
65
+
56
66
  ## Custom backend (sandbox / fixtures)
57
67
 
58
- `SodaxConfig` does not expose a typed slot to inject a custom `IConfigApi` implementation at construction. Two supported patterns:
68
+ `SodaxConfig` does not expose a typed slot to inject a custom `IConfigApiV1` implementation at construction. Two supported patterns:
59
69
 
60
70
  1. **Point at a local mock backend** via `SodaxConfig.api.baseURL`:
61
71
 
@@ -66,16 +76,17 @@ if (!submitResult.ok) return;
66
76
  await sodax.config.initialize();
67
77
  ```
68
78
 
69
- `SodaxConfig.api` is `ApiConfig` (`{ baseURL, timeout, headers }`) — pass any subset via `DeepPartial`.
79
+ `SodaxConfig.api` is `ApiConfig` — either the flat `BaseApiConfig` (`{ baseURL, timeout, headers }`, shared by the base API and the swaps client) or the nested `CustomApiConfig` (`{ baseApiConfig?, swapsApiConfig? }`) to point the swaps API at its own endpoint. Pass any subset via `DeepPartial`. See [`./swaps-api.md`](swaps-api.md) § "Custom endpoint for the swaps API".
70
80
 
71
81
  2. **Inject your own `BackendApiService`-compatible mock at the app layer** (dependency-injected where you control the `Sodax` instance), rather than via the constructor.
72
82
 
73
- The `IConfigApi` interface itself still matters for both patterns — every method returns `Promise<Result<T>>` in v2, so any mock or local server must conform. See [`../architecture.md`](../architecture.md) § 4 "Custom backend" for the authoritative reference.
83
+ The `IConfigApiV1` interface itself still matters for both patterns — every method returns `Promise<Result<T>>` in v2, so any mock or local server must conform. See [`../architecture.md`](../architecture.md) § 4 "Custom backend" for the authoritative reference.
74
84
 
75
85
  ## Cross-references
76
86
 
77
87
  - v1 → v2 migration of `BackendApiService` (the load-bearing change: every method now returns `Promise<Result<T>>`): [`features/backend-api.md`](../../../migration-v1-to-v2/knowledge/features/backend-api.md).
78
- - The full `submitSwapTx` flow with `createIntent` upstream: [`./swap.md`](swap.md) § "Backend submit-tx flow".
88
+ - The full submit-tx flow with `createIntent` upstream: [`./swap.md`](swap.md) § "Backend submit-tx flow".
89
+ - The full typed Swaps API v2 client (`sodax.api.swaps`, 21 endpoints — quote, create-intent, submit-tx, fees, status, …): [`./swaps-api.md`](swaps-api.md).
79
90
  - Partner-fee handling (separate service): [`./partner.md`](partner.md).
80
91
  - Stuck-asset recovery (separate service): [`./recovery.md`](recovery.md).
81
92
  - Error model context fields (`error.context.api`, `error.context.method`): [`../reference/`](../reference/) § 3.
@@ -14,7 +14,7 @@ A bridge call deposits the source token into its vault on the hub, then triggers
14
14
 
15
15
  ```ts
16
16
  sodax.bridge.bridge<K>(action: BridgeAction<K, false>): Promise<Result<TxHashPair, SodaxError>>;
17
- sodax.bridge.createBridgeIntent<K, Raw>(action): Promise<Result<CreateBridgeIntentResult<K, Raw>, SodaxError>>;
17
+ sodax.bridge.createBridgeIntent<K, Raw>(action): Promise<Result<IntentTxResult<K, Raw>, SodaxError>>;
18
18
  sodax.bridge.approve<K, Raw>(args): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
19
19
  sodax.bridge.isAllowanceValid<K, Raw>(args): Promise<Result<boolean, SodaxError>>;
20
20
 
@@ -28,14 +28,14 @@ sodax.bridge.getFee(inputAmount: bigint): bigint;
28
28
  ## Action params shape
29
29
 
30
30
  ```ts
31
- type CreateBridgeParams<K extends SpokeChainKey> = {
31
+ type CreateBridgeIntentParams<K extends SpokeChainKey> = {
32
32
  srcChainKey: K;
33
- srcAddress: GetAddressType<K>;
34
- srcAsset: `0x${string}`; // source token address (spoke chain)
33
+ srcAddress: string; // source wallet (spoke chain)
34
+ srcToken: string; // source token address (spoke chain)
35
35
  amount: bigint;
36
36
  dstChainKey: SpokeChainKey;
37
- dstAddress: string; // destination wallet (chain-specific format)
38
- dstAsset: `0x${string}`; // destination token address (must share vault with srcAsset)
37
+ dstToken: string; // destination token address (must share vault with srcToken)
38
+ recipient: string; // destination receiver (chain-specific format)
39
39
  };
40
40
  ```
41
41
 
@@ -48,11 +48,11 @@ const result = await sodax.bridge.bridge({
48
48
  params: {
49
49
  srcChainKey: ChainKeys.ARBITRUM_MAINNET,
50
50
  srcAddress: '0x…',
51
- srcAsset: USDC_ARBITRUM.address,
51
+ srcToken: USDC_ARBITRUM.address,
52
52
  amount: parseUnits('100', 6),
53
53
  dstChainKey: ChainKeys.STELLAR_MAINNET,
54
- dstAddress: 'G…',
55
- dstAsset: USDC_STELLAR.address,
54
+ dstToken: USDC_STELLAR.address,
55
+ recipient: 'G…',
56
56
  },
57
57
  raw: false,
58
58
  walletProvider: evmWp,
@@ -72,7 +72,7 @@ const result = await sodax.bridge.createBridgeIntent({
72
72
  });
73
73
 
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 own relay infrastructure if needed.
77
77
  ```
78
78
 
@@ -99,11 +99,11 @@ const result = await sodax.bridge.bridge({
99
99
  params: {
100
100
  srcChainKey: ChainKeys.SONIC_MAINNET,
101
101
  srcAddress: (await evmWp.getWalletAddress()) as `0x${string}`,
102
- srcAsset: sodaSonic.address,
102
+ srcToken: sodaSonic.address,
103
103
  amount: parseUnits('1', sodaSonic.decimals),
104
104
  dstChainKey: ChainKeys.BASE_MAINNET,
105
- dstAddress: recipientOnBase,
106
- dstAsset: sodaBase.address,
105
+ dstToken: sodaBase.address,
106
+ recipient: recipientOnBase,
107
107
  },
108
108
  raw: false,
109
109
  walletProvider: evmWp,
@@ -147,7 +147,7 @@ if (result.ok) {
147
147
  | Method | Success type |
148
148
  |---|---|
149
149
  | `bridge` | `TxHashPair` |
150
- | `createBridgeIntent` | `CreateBridgeIntentResult<K, Raw>` = `{ tx: TxReturnType<K, Raw>, intent, relayData }` |
150
+ | `createBridgeIntent` | `IntentTxResult<K, Raw>` = `{ tx: TxReturnType<K, Raw>, relayData }` |
151
151
  | `approve` | `TxReturnType<K, Raw>` |
152
152
  | `isAllowanceValid` | `boolean` |
153
153
  | `getBridgeableAmount` | `BridgeLimit = { amount, decimals, type }` |
@@ -169,4 +169,5 @@ if (result.ok) {
169
169
 
170
170
  - v1 → v2 bridge migration: [`features/bridge.md`](../../../migration-v1-to-v2/knowledge/features/bridge.md).
171
171
  - Stellar destinations need a trustline first: [`../chain-specifics.md`](../chain-specifics.md).
172
+ - NEAR destinations need NEP-141 storage registration first: [`../chain-specifics.md`](../chain-specifics.md).
172
173
  - Hub-and-spoke vault architecture: [`../architecture.md`](../architecture.md) § 1.
@@ -40,11 +40,11 @@ sodax.dex.clService.claimRewards<K>(action): Promise<Result<TxHashPair, SodaxErr
40
40
 
41
41
  sodax.dex.clService.getPools(): PoolKey[]; // synchronous in v2
42
42
  sodax.dex.clService.getPoolData(poolKey, publicClient): Promise<Result<PoolData, SodaxError>>;
43
- sodax.dex.clService.getPositionInfo(tokenId, poolKey, publicClient): Promise<Result<PositionInfo, SodaxError>>;
43
+ sodax.dex.clService.getPositionInfo(tokenId, publicClient): Promise<Result<ClPositionInfo, SodaxError>>;
44
44
  sodax.dex.clService.getAssetsForPool(srcChainKey, poolKey): { token0, token1 }; // chain-key-first; sync
45
45
 
46
46
  // Static math helpers (still throw on error — utility class):
47
- ClService.priceToTick(price): number;
47
+ ClService.priceToTick(price, token0, token1, tickSpacing): bigint;
48
48
  ClService.calculateAmount0FromAmount1(...): bigint;
49
49
  ClService.calculateAmount1FromAmount0(...): bigint;
50
50
  ```
@@ -58,7 +58,7 @@ type CreateAssetDepositParams<K extends SpokeChainKey> = {
58
58
  asset: `0x${string}`; // spoke-side token address
59
59
  amount: bigint;
60
60
  poolToken: `0x${string}`; // hub-side pool token (vault address)
61
- dst?: { chainKey: SpokeChainKey; address: string }; // optional cross-chain delivery
61
+ dst?: { dstChainKey: SpokeChainKey; dstAddress: string }; // optional cross-chain delivery
62
62
  };
63
63
 
64
64
  type CreateAssetWithdrawParams<K> = { /* same shape */ };
@@ -67,8 +67,8 @@ type ClSupplyParams<K> = {
67
67
  srcChainKey: K;
68
68
  srcAddress: GetAddressType<K>;
69
69
  poolKey: PoolKey;
70
- tickLower: number;
71
- tickUpper: number;
70
+ tickLower: bigint;
71
+ tickUpper: bigint;
72
72
  liquidity: bigint;
73
73
  amount0Max: bigint;
74
74
  amount1Max: bigint;
@@ -117,8 +117,8 @@ const result = await sodax.dex.clService.supplyLiquidity({
117
117
  srcChainKey: ChainKeys.ARBITRUM_MAINNET,
118
118
  srcAddress: '0x…',
119
119
  poolKey: { /* { currency0, currency1, fee, tickSpacing, hooks } */ },
120
- tickLower: -887220,
121
- tickUpper: 887220,
120
+ tickLower: -887220n,
121
+ tickUpper: 887220n,
122
122
  liquidity: 1000000n,
123
123
  amount0Max: parseUnits('100', 6),
124
124
  amount1Max: parseUnits('100', 6),