@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.
- package/.claude-plugin/plugin.json +1 -9
- package/AGENTS.md +119 -14
- package/README.md +5 -2
- package/package.json +1 -1
- package/skills/sodax-build/SKILL.md +90 -0
- package/skills/sodax-build/knowledge/README.md +35 -0
- package/skills/sodax-build/knowledge/brief-template.md +41 -0
- package/skills/sodax-build/knowledge/chains-and-assets.md +26 -0
- package/skills/sodax-build/knowledge/example-sessions.md +84 -0
- package/skills/sodax-build/knowledge/feature-catalog.md +51 -0
- package/skills/sodax-build/knowledge/glossary.md +35 -0
- package/skills/sodax-build/knowledge/handoff.md +60 -0
- package/skills/sodax-build/knowledge/interview-guide.md +66 -0
- package/skills/sodax-build/knowledge/monetization.md +37 -0
- package/skills/sodax-build/knowledge/use-case-gallery.md +32 -0
- package/skills/sodax-dapp-kit/SKILL.md +6 -2
- package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +65 -0
- package/skills/sodax-dapp-kit/bitcoin/SKILL.md +57 -0
- package/skills/sodax-dapp-kit/bridge/SKILL.md +59 -0
- package/skills/sodax-dapp-kit/dex/SKILL.md +60 -0
- package/skills/sodax-dapp-kit/integration/knowledge/README.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/README.md +3 -2
- package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +71 -11
- package/skills/sodax-dapp-kit/integration/knowledge/features/bitcoin.md +10 -6
- package/skills/sodax-dapp-kit/integration/knowledge/features/dex.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +112 -0
- package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +6 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md +8 -8
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +168 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +4 -4
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md +3 -0
- package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +67 -6
- package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +49 -0
- package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +54 -0
- package/skills/sodax-dapp-kit/migration/SKILL.md +64 -0
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +2 -2
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +19 -10
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md +2 -2
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +3 -3
- package/skills/sodax-dapp-kit/money-market/SKILL.md +61 -0
- package/skills/sodax-dapp-kit/staking/SKILL.md +60 -0
- package/skills/sodax-dapp-kit/swap/SKILL.md +64 -0
- package/skills/sodax-sdk/SKILL.md +11 -6
- package/skills/sodax-sdk/backend-api/SKILL.md +21 -15
- package/skills/sodax-sdk/bridge/SKILL.md +4 -0
- package/skills/sodax-sdk/dex/SKILL.md +5 -1
- package/skills/sodax-sdk/integration/knowledge/README.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/architecture.md +24 -21
- package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
- package/skills/sodax-sdk/integration/knowledge/features/README.md +2 -1
- package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +27 -16
- package/skills/sodax-sdk/integration/knowledge/features/bridge.md +15 -14
- package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
- package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +175 -0
- package/skills/sodax-sdk/integration/knowledge/features/migration.md +73 -28
- package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
- package/skills/sodax-sdk/integration/knowledge/features/partner.md +27 -4
- package/skills/sodax-sdk/integration/knowledge/features/recovery.md +5 -4
- package/skills/sodax-sdk/integration/knowledge/features/staking.md +2 -2
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +42 -24
- package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
- package/skills/sodax-sdk/integration/knowledge/quickstart.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -0
- package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
- package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +34 -2
- package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +102 -0
- package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +28 -4
- package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
- package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +40 -4
- package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +32 -9
- package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
- package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -4
- package/skills/sodax-sdk/leverage-yield/SKILL.md +50 -0
- package/skills/sodax-sdk/migration/SKILL.md +5 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +3 -3
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -5
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +23 -23
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/migration.md +29 -27
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +10 -5
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +18 -16
- package/skills/sodax-sdk/money-market/SKILL.md +7 -3
- package/skills/sodax-sdk/partner/SKILL.md +4 -0
- package/skills/sodax-sdk/recovery/SKILL.md +5 -1
- package/skills/sodax-sdk/staking/SKILL.md +4 -0
- package/skills/sodax-sdk/swap/SKILL.md +8 -3
- package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
- package/skills/sodax-wallet-sdk-core/SKILL.md +7 -3
- package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/evm/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/icon/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/injective/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
- package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/testing.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
- package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/near/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/solana/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/stacks/SKILL.md +53 -0
- package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +54 -0
- package/skills/sodax-wallet-sdk-core/sui/SKILL.md +53 -0
- package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
- package/skills/sodax-wallet-sdk-react/bridge-to-sdk/SKILL.md +56 -0
- package/skills/sodax-wallet-sdk-react/connect/SKILL.md +59 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +10 -10
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +4 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/ssr-setup.md +24 -19
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +1 -1
- package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +51 -0
- package/skills/sodax-wallet-sdk-react/switch-chain/SKILL.md +51 -0
- package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +54 -0
- 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;
|
|
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
|
-
|
|
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
|
|
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
|
|
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,
|
|
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
|
|
131
|
+
import { Sodax, type SodaxOptions } from '@sodax/sdk';
|
|
131
132
|
|
|
132
|
-
new Sodax(config?:
|
|
133
|
+
new Sodax(config?: SodaxOptions): Sodax;
|
|
133
134
|
```
|
|
134
135
|
|
|
135
|
-
`
|
|
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
|
-
|
|
138
|
-
|
|
139
|
-
- `
|
|
140
|
-
- `
|
|
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
|
-
- `
|
|
144
|
-
- `
|
|
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 }`)
|
|
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'
|
|
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(
|
|
452
|
-
- `relayTxAndWaitPacket({
|
|
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({ /*
|
|
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 —
|
|
1
|
+
# Chain specifics — chain quirks
|
|
2
2
|
|
|
3
|
-
EVM chains
|
|
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
|
|
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
|
|
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
|
-
###
|
|
74
|
+
### Bound Exchange (auth + trading wallet)
|
|
55
75
|
|
|
56
|
-
SODAX uses the
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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,
|
|
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:**
|
|
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.
|
|
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 `
|
|
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
|
|
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 — `
|
|
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.
|
|
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
|
|
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 `
|
|
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 }`)
|
|
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 `
|
|
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
|
|
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<
|
|
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
|
|
31
|
+
type CreateBridgeIntentParams<K extends SpokeChainKey> = {
|
|
32
32
|
srcChainKey: K;
|
|
33
|
-
srcAddress:
|
|
34
|
-
|
|
33
|
+
srcAddress: string; // source wallet (spoke chain)
|
|
34
|
+
srcToken: string; // source token address (spoke chain)
|
|
35
35
|
amount: bigint;
|
|
36
36
|
dstChainKey: SpokeChainKey;
|
|
37
|
-
|
|
38
|
-
|
|
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
|
-
|
|
51
|
+
srcToken: USDC_ARBITRUM.address,
|
|
52
52
|
amount: parseUnits('100', 6),
|
|
53
53
|
dstChainKey: ChainKeys.STELLAR_MAINNET,
|
|
54
|
-
|
|
55
|
-
|
|
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,
|
|
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
|
-
|
|
102
|
+
srcToken: sodaSonic.address,
|
|
103
103
|
amount: parseUnits('1', sodaSonic.decimals),
|
|
104
104
|
dstChainKey: ChainKeys.BASE_MAINNET,
|
|
105
|
-
|
|
106
|
-
|
|
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` | `
|
|
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,
|
|
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):
|
|
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?: {
|
|
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:
|
|
71
|
-
tickUpper:
|
|
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: -
|
|
121
|
-
tickUpper:
|
|
120
|
+
tickLower: -887220n,
|
|
121
|
+
tickUpper: 887220n,
|
|
122
122
|
liquidity: 1000000n,
|
|
123
123
|
amount0Max: parseUnits('100', 6),
|
|
124
124
|
amount1Max: parseUnits('100', 6),
|