@sodax/skills 2.0.0-rc.8 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -0
- package/AGENTS.md +123 -13
- 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/migration.md +1 -1
- 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/features/migration.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 +54 -50
- package/skills/sodax-sdk/backend-api/SKILL.md +58 -0
- package/skills/sodax-sdk/bridge/SKILL.md +53 -0
- package/skills/sodax-sdk/dex/SKILL.md +54 -0
- package/skills/sodax-sdk/integration/knowledge/README.md +5 -3
- package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/architecture.md +26 -39
- package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
- package/skills/sodax-sdk/integration/knowledge/features/README.md +6 -3
- package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +92 -0
- package/skills/sodax-sdk/integration/knowledge/features/bridge.md +48 -11
- 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/{icx-bnusd-baln.md → migration.md} +75 -30
- package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
- package/skills/sodax-sdk/integration/knowledge/features/partner.md +86 -0
- package/skills/sodax-sdk/integration/knowledge/features/recovery.md +51 -0
- package/skills/sodax-sdk/integration/knowledge/features/staking.md +8 -3
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +106 -22
- 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 +69 -0
- 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 +6 -10
- 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 +2 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/README.md +4 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +92 -0
- 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/{icx-bnusd-baln.md → migration.md} +31 -29
- 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 +64 -0
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +35 -0
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +8 -3
- 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 +19 -17
- package/skills/sodax-sdk/money-market/SKILL.md +56 -0
- package/skills/sodax-sdk/partner/SKILL.md +55 -0
- package/skills/sodax-sdk/recovery/SKILL.md +53 -0
- package/skills/sodax-sdk/staking/SKILL.md +53 -0
- package/skills/sodax-sdk/swap/SKILL.md +72 -0
- 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
- package/skills/sodax-sdk/integration/knowledge/features/auxiliary-services.md +0 -189
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/auxiliary-services.md +0 -156
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-sdk-dex
|
|
3
|
+
description: 'Granular skill for the @sodax/sdk v2 DEX feature only — Uniswap-V3-style concentrated liquidity positions on the hub, plus AssetService for hub-asset deposit/withdraw. Use when the task is LP positions (e.g. "Sodax concentrated liquidity", "create LP position on Sodax", "increase liquidity", "decrease liquidity", "claim LP fees", "deposit hub assets for LP"). Covers BOTH integration and migration. Skill links into the parent sodax-sdk knowledge tree. For React dapps, prefer sodax-dapp-kit.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# DEX (Core SDK granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for `DexService` — facade owning `clService: ClService` (concentrated liquidity) and `assetService: AssetService` (hub-asset deposit/withdraw). Access via `sodax.dex.clService` and `sodax.dex.assetService`. Feature tag for errors: `'dex'`.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
1. **New code or v1 → v2 port?**
|
|
17
|
+
2. **Which operation?**
|
|
18
|
+
- LP: `supplyLiquidity` (mint new), `increaseLiquidity`, `decreaseLiquidity`, `claimRewards`.
|
|
19
|
+
- Assets: `deposit` (spoke → hub-asset wrapper), `withdraw` (hub → spoke).
|
|
20
|
+
3. **Does the position require an asset deposit first?** LP positions hold hub assets; the user must deposit from a spoke chain before opening a position.
|
|
21
|
+
4. **Signed or unsigned-tx flow?**
|
|
22
|
+
|
|
23
|
+
## Integration workflow
|
|
24
|
+
|
|
25
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
|
|
26
|
+
2. [`../integration/knowledge/features/dex.md`](../integration/knowledge/features/dex.md) — `ClService` + `AssetService` APIs, position lifecycle, tick math notes.
|
|
27
|
+
3. Path-specific recipe:
|
|
28
|
+
- Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
|
|
29
|
+
- Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
|
|
30
|
+
4. Errors (`feature: 'dex'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
|
|
31
|
+
|
|
32
|
+
### DEX-specific anti-patterns
|
|
33
|
+
|
|
34
|
+
- **Reaching for `sodax.cl` / `sodax.assets`.** Wrong paths — both services are reached via `sodax.dex` (i.e. `sodax.dex.clService.*` and `sodax.dex.assetService.*`). The `Sodax` facade exposes only `dex`.
|
|
35
|
+
- **Skipping `assetService.deposit` before opening a position.** LP positions reference hub-asset addresses; without deposit there's nothing to provide.
|
|
36
|
+
- **Confusing pool addresses on Sonic with spoke token addresses.** CL pools live on Sonic; the user-facing tokens live on spokes.
|
|
37
|
+
|
|
38
|
+
## Migration workflow (v1 → v2)
|
|
39
|
+
|
|
40
|
+
1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
|
|
41
|
+
2. [`../migration-v1-to-v2/knowledge/features/dex.md`](../migration-v1-to-v2/knowledge/features/dex.md) — v1 `ConcentratedLiquidityError` / `AssetServiceError` → v2 `SodaxError<C>` with the appropriate `feature` tag.
|
|
42
|
+
|
|
43
|
+
## Verification
|
|
44
|
+
|
|
45
|
+
1. `pnpm tsc --noEmit` clean.
|
|
46
|
+
2. Every `await sodax.dex.clService.<method>(...)` and `await sodax.dex.assetService.<method>(...)` has `if (!result.ok)`.
|
|
47
|
+
3. No `instanceof ConcentratedLiquidityError` / `AssetServiceError`.
|
|
48
|
+
|
|
49
|
+
## Related granular skills (same family)
|
|
50
|
+
|
|
51
|
+
- [`../recovery/SKILL.md`](../recovery/SKILL.md) — `RecoveryService` for stuck hub-wallet LP assets.
|
|
52
|
+
- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — `BackendApiService` for position reads if surfaced there.
|
|
53
|
+
|
|
54
|
+
For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).
|
|
@@ -13,11 +13,13 @@ This tree documents v2 of the SDK for **new consumers** building against it. If
|
|
|
13
13
|
| [`features/staking.md`](features/staking.md) | `StakingService`: SODA → xSoda — stake, unstake, instant unstake, claim, cancel; ratio + info reads. |
|
|
14
14
|
| [`features/bridge.md`](features/bridge.md) | `BridgeService`: cross-chain token transfer via vault — `bridge`, `createBridgeIntent`, `getBridgeableAmount`, `getBridgeableTokens`. |
|
|
15
15
|
| [`features/dex.md`](features/dex.md) | `ClService` (concentrated liquidity) + `AssetService`: position lifecycle (mint/increase/decrease), claim rewards, asset deposit/withdraw. |
|
|
16
|
-
| [`features/
|
|
17
|
-
| [`features/
|
|
16
|
+
| [`features/migration.md`](features/migration.md) | `MigrationService` (the SDK module): ICX, bnUSD, BALN sub-services + lock management. |
|
|
17
|
+
| [`features/partner.md`](features/partner.md) | `PartnerService` — partner-fee handling. |
|
|
18
|
+
| [`features/recovery.md`](features/recovery.md) | `RecoveryService` — withdraw stuck hub-wallet assets. |
|
|
19
|
+
| [`features/backend-api.md`](features/backend-api.md) | `BackendApiService` — HTTP client for backend reads + swap-tx submission. |
|
|
18
20
|
| [`recipes/`](recipes/) | Copy-pasteable patterns: SDK initialization, `Result` + error discrimination, raw-tx flow, signed-tx flow, chain-key narrowing + cast-at-boundary, testing (mocks/stubs), gas estimation, backend-server init. |
|
|
19
21
|
| [`reference/`](reference/) | Lookup tables: 20-chain `ChainKeys` table with family + relay id, `I*WalletProvider` interfaces, 13 `SodaxErrorCode` meanings + per-feature narrow unions, public API surface (incl. `@sodax/types` re-export rule), glossary. |
|
|
20
|
-
| [`chain-specifics.md`](chain-specifics.md) | Non-EVM quirks — Stellar trustline check/request, Bitcoin PSBT +
|
|
22
|
+
| [`chain-specifics.md`](chain-specifics.md) | Non-EVM quirks — Stellar trustline check/request, Bitcoin PSBT + Bound Exchange auth/session, Solana PDA derivation, ICON Hana wallet + chain-key string, NEAR connector discovery. |
|
|
21
23
|
|
|
22
24
|
## Reading order for a new integrator
|
|
23
25
|
|
|
@@ -32,7 +32,7 @@ DO / DO NOT / workflow / stop conditions for AI agents writing `@sodax/sdk` v2 c
|
|
|
32
32
|
- **DO NOT** import from `@sodax/sdk/dist/...`. Deep imports are unstable across releases; only the package root barrel is the public contract.
|
|
33
33
|
- **DO NOT** add `@sodax/types` as a separate dependency. It's bundled / re-exported via `@sodax/sdk`. Adding it independently invites version skew.
|
|
34
34
|
- **DO NOT** destructure cross-chain mutation results as arrays — `[a, b] = result.value` is wrong. The shape is `TxHashPair = { srcChainTxHash, dstChainTxHash }` (object). This applies to `bridge.bridge`, `staking.{stake,unstake,instantUnstake,claim,cancelUnstake}`, `dex.assetService.{deposit,withdraw}`, `dex.clService.{supplyLiquidity,increaseLiquidity,decreaseLiquidity,claimRewards}`, `moneyMarket.{supply,borrow,withdraw,repay}`, `migration.{migratebnUSD,migrateIcxToSoda,revertMigrateSodaToIcx,migrateBaln}` — all of them.
|
|
35
|
-
- **DO NOT**
|
|
35
|
+
- **DO NOT** look for MM reserve/position reads on `sodax.backendApi`. `getReservesData`, `getUserReservesData`, `getATokensBalances`, `getReservesHumanized`, etc. live on the `sodax.moneyMarket.data` sub-service (`MoneyMarketDataService`), and they throw on failure (bare `Promise<T>`, not a `Result`) — wrap them in try/catch.
|
|
36
36
|
- **DO NOT** reach for an `intentRelayApi` property on the `Sodax` instance — there is no such property. The relay layer is exposed as two top-level functions, `relayTxAndWaitPacket` and `submitTransaction` (re-exported from `@sodax/sdk`). Call them directly if you need custom relay orchestration.
|
|
37
37
|
- **DO NOT** call `getStakeRatio` and treat its return as `Result<bigint>`. It's `Result<[xSodaAmount, previewDepositAmount]>` — a tuple of two bigints.
|
|
38
38
|
- **DO NOT** assume `BalnSwapService` lock-management methods (`stake`, `unstake`, `claim`, `claimUnstaked`, `cancelUnstake`, `getDetailedUserLocks`) return `Result<T>`. They still throw on error in v2 — known carve-out. Wrap them in `try/catch`.
|
|
@@ -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
|
|
|
@@ -356,23 +359,7 @@ class SodaxError<C extends SodaxErrorCode = SodaxErrorCode> extends Error {
|
|
|
356
359
|
|
|
357
360
|
### The 13 codes
|
|
358
361
|
|
|
359
|
-
|
|
360
|
-
|---|---|
|
|
361
|
-
| `VALIDATION_FAILED` | Pre-flight invariant tripped. |
|
|
362
|
-
| `INTENT_CREATION_FAILED` | Building the intent / payload failed. |
|
|
363
|
-
| `EXECUTION_FAILED` | Orchestrator-level catch-all for multi-step ops. |
|
|
364
|
-
| `TX_VERIFICATION_FAILED` | Spoke-side `verifyTxHash` returned false / threw. |
|
|
365
|
-
| `TX_SUBMIT_FAILED` | Spoke tx landed; relay POST submit failed. |
|
|
366
|
-
| `RELAY_TIMEOUT` | Destination packet didn't reach `executed` within timeout. |
|
|
367
|
-
| `RELAY_FAILED` | Relay polling outage / unrecognised relay error. |
|
|
368
|
-
| `APPROVE_FAILED` | Token approval call failed. |
|
|
369
|
-
| `ALLOWANCE_CHECK_FAILED` | Reading on-chain allowance failed. |
|
|
370
|
-
| `GAS_ESTIMATION_FAILED` | Gas estimation returned an error. |
|
|
371
|
-
| `LOOKUP_FAILED` | Read-only on-chain query / off-chain config fetch. |
|
|
372
|
-
| `EXTERNAL_API_ERROR` | Upstream API call failed (solver, backend). |
|
|
373
|
-
| `UNKNOWN` | Last-resort catch in an outer `try`. Should be rare. |
|
|
374
|
-
|
|
375
|
-
The full per-code semantics, common context fields, per-feature narrow unions, and retry guidance are in [`reference/`](reference/) § "Error codes".
|
|
362
|
+
The closed code vocabulary is the same 13 names across every feature — see [`reference/error-codes.md`](reference/error-codes.md) for the full table, per-code semantics, common `context` field shapes, per-feature narrow unions, and retry guidance.
|
|
376
363
|
|
|
377
364
|
### `(feature, code)` discrimination
|
|
378
365
|
|
|
@@ -398,7 +385,7 @@ Public methods declare narrow code unions via `Extract<SodaxErrorCode, ...>`:
|
|
|
398
385
|
```ts
|
|
399
386
|
type CreateSupplyIntentErrorCode = Extract<
|
|
400
387
|
SodaxErrorCode,
|
|
401
|
-
'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN'
|
|
388
|
+
'USER_REJECTED' | 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN'
|
|
402
389
|
>;
|
|
403
390
|
```
|
|
404
391
|
|
|
@@ -464,8 +451,8 @@ Use these in cross-bundle code (apps with mixed ESM/CJS resolution, monorepos wi
|
|
|
464
451
|
|
|
465
452
|
Cross-chain coordination is exposed as two top-level functions (re-exported from `@sodax/sdk`'s barrel):
|
|
466
453
|
|
|
467
|
-
- `submitTransaction(
|
|
468
|
-
- `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`.
|
|
469
456
|
|
|
470
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.
|
|
471
458
|
|
|
@@ -491,7 +478,7 @@ The single shared mapper from a relay-layer error to a `SodaxError`. Every featu
|
|
|
491
478
|
import { mapRelayFailure, relayTxAndWaitPacket } from '@sodax/sdk';
|
|
492
479
|
|
|
493
480
|
try {
|
|
494
|
-
await relayTxAndWaitPacket({ /*
|
|
481
|
+
await relayTxAndWaitPacket({ /* srcTxHash, data, chainKey, relayerApiEndpoint, timeout, pollTxHash? */ });
|
|
495
482
|
} catch (e) {
|
|
496
483
|
const sodaxError = mapRelayFailure(e, {
|
|
497
484
|
feature: 'swap',
|
|
@@ -518,7 +505,7 @@ You drop down to the relay layer only when:
|
|
|
518
505
|
|
|
519
506
|
### Cross-references
|
|
520
507
|
|
|
521
|
-
- `RecoveryService` for pulling stuck hub-wallet assets back to a spoke chain: see [`features/
|
|
508
|
+
- `RecoveryService` for pulling stuck hub-wallet assets back to a spoke chain: see [`features/recovery.md`](features/recovery.md).
|
|
522
509
|
- Per-feature error codes related to relay (e.g. `'TX_SUBMIT_FAILED'`, `'RELAY_TIMEOUT'`): [`reference/`](reference/) § "Error codes".
|
|
523
510
|
|
|
524
511
|
---
|
|
@@ -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,11 +9,14 @@ 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
|
-
| [`
|
|
13
|
-
| [`
|
|
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. |
|
|
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. |
|
|
14
|
+
| [`partner.md`](partner.md) | `PartnerService` | Partner-fee handling: token approval, auto-swap preferences, fee-claim flows. |
|
|
15
|
+
| [`recovery.md`](recovery.md) | `RecoveryService` | Withdraw stuck hub-wallet assets back to a spoke chain. |
|
|
16
|
+
| [`backend-api.md`](backend-api.md) | `BackendApiService` | HTTP client for backend services: swap-tx submission, intent / orderbook lookups, money-market reads. |
|
|
14
17
|
|
|
15
18
|
All feature services are constructed and wired by the `Sodax` facade. You don't instantiate them directly — access them via `sodax.swaps`, `sodax.moneyMarket`, etc. See [`../architecture.md`](../architecture.md) for the service graph.
|
|
16
19
|
|
|
17
20
|
## Cross-references to migration
|
|
18
21
|
|
|
19
|
-
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.
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Backend API — `BackendApiService`
|
|
2
|
+
|
|
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
|
+
|
|
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
|
+
|
|
7
|
+
## Methods
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
// Swap-related reads
|
|
11
|
+
sodax.backendApi.getOrderbook(...): Promise<Result<OrderbookResponse>>; // object: { total: number; data: Array<{ intentState, intentData }> } — NOT an array
|
|
12
|
+
sodax.backendApi.getIntentByHash(intentHash, config?): Promise<Result<IntentResponse>>;
|
|
13
|
+
sodax.backendApi.getIntentByTxHash(txHash, config?): 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>>;
|
|
19
|
+
|
|
20
|
+
// Money-market reads (these are the canonical reads for MM positions/reserves;
|
|
21
|
+
// MoneyMarketService does NOT expose getReservesData / getUserReservesData / etc.)
|
|
22
|
+
sodax.backendApi.getMoneyMarketPosition(...): Promise<Result<...>>;
|
|
23
|
+
sodax.backendApi.getAllMoneyMarketAssets(config?): Promise<Result<MoneyMarketAsset[]>>;
|
|
24
|
+
sodax.backendApi.getMoneyMarketAsset(reserveAddress, config?): Promise<Result<MoneyMarketAsset>>;
|
|
25
|
+
sodax.backendApi.getMoneyMarketAssetBorrowers(...): Promise<Result<...>>;
|
|
26
|
+
sodax.backendApi.getMoneyMarketAssetSuppliers(...): Promise<Result<...>>;
|
|
27
|
+
sodax.backendApi.getAllMoneyMarketBorrowers(...): Promise<Result<...>>;
|
|
28
|
+
|
|
29
|
+
// Config-API methods (used internally by ConfigService — implements `IConfigApiV1`)
|
|
30
|
+
sodax.backendApi.getAllConfig(config?): Promise<Result<GetAllConfigApiResponse>>;
|
|
31
|
+
sodax.backendApi.getChains(config?): Promise<Result<GetChainsApiResponse>>;
|
|
32
|
+
sodax.backendApi.getSwapTokens(config?): Promise<Result<GetSwapTokensApiResponse>>;
|
|
33
|
+
sodax.backendApi.getSwapTokensByChainId(...): Promise<Result<XToken[]>>;
|
|
34
|
+
sodax.backendApi.getMoneyMarketTokens(config?): Promise<Result<GetMoneyMarketTokensApiResponse>>;
|
|
35
|
+
sodax.backendApi.getMoneyMarketReserveAssets(...): Promise<Result<...>>;
|
|
36
|
+
sodax.backendApi.getMoneyMarketTokensByChainId(...): Promise<Result<XToken[]>>;
|
|
37
|
+
sodax.backendApi.getRelayChainIdMap(config?): Promise<Result<GetRelayChainIdMapApiResponse>>;
|
|
38
|
+
```
|
|
39
|
+
|
|
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).
|
|
43
|
+
|
|
44
|
+
## Common call shape — submit swap tx (`sodax.api.swaps.submitTx`)
|
|
45
|
+
|
|
46
|
+
After `sodax.swaps.createIntent({ params, raw: false, walletProvider })` returns:
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
const submitResult = await sodax.api.swaps.submitTx({
|
|
50
|
+
txHash: spokeTxHash as string,
|
|
51
|
+
srcChainKey: src.chain,
|
|
52
|
+
walletAddress: '0x…',
|
|
53
|
+
intent, // IntentRequestV2 (bigint fields) — the createIntent intent passes through
|
|
54
|
+
relayData: relayData.payload, // string, not the RelayExtraData object
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
if (!submitResult.ok) return;
|
|
58
|
+
```
|
|
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
|
+
|
|
66
|
+
## Custom backend (sandbox / fixtures)
|
|
67
|
+
|
|
68
|
+
`SodaxConfig` does not expose a typed slot to inject a custom `IConfigApiV1` implementation at construction. Two supported patterns:
|
|
69
|
+
|
|
70
|
+
1. **Point at a local mock backend** via `SodaxConfig.api.baseURL`:
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
const sodax = new Sodax({
|
|
74
|
+
api: { baseURL: 'http://localhost:4000' },
|
|
75
|
+
});
|
|
76
|
+
await sodax.config.initialize();
|
|
77
|
+
```
|
|
78
|
+
|
|
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".
|
|
80
|
+
|
|
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.
|
|
82
|
+
|
|
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.
|
|
84
|
+
|
|
85
|
+
## Cross-references
|
|
86
|
+
|
|
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).
|
|
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).
|
|
90
|
+
- Partner-fee handling (separate service): [`./partner.md`](partner.md).
|
|
91
|
+
- Stuck-asset recovery (separate service): [`./recovery.md`](recovery.md).
|
|
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,10 +72,46 @@ 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
|
|
|
79
|
+
### Hub as source (Sonic → spoke)
|
|
80
|
+
|
|
81
|
+
`srcChainKey` accepts `ChainKeys.SONIC_MAINNET` too — the SDK routes through the user's hub-wallet abstraction (instead of a spoke deposit) and then triggers the destination withdrawal. The call shape is the same; only the chain key changes:
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
const sodaSonic = sodax.config.findSupportedTokenBySymbol(ChainKeys.SONIC_MAINNET, 'SODA');
|
|
85
|
+
const sodaBase = sodax.config.findSupportedTokenBySymbol(ChainKeys.BASE_MAINNET, 'SODA');
|
|
86
|
+
if (!sodaSonic || !sodaBase) throw new Error('SODA missing from config');
|
|
87
|
+
|
|
88
|
+
// 1. Confirm the pair is vault-bridgeable (synchronous, config-derived).
|
|
89
|
+
if (!sodax.bridge.isBridgeable({ from: sodaSonic, to: sodaBase })) {
|
|
90
|
+
// Fall back to swap if needed — different vaults aren't bridgeable.
|
|
91
|
+
return;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
// 2. (Optional) check the vault-side cap.
|
|
95
|
+
const limit = await sodax.bridge.getBridgeableAmount(sodaSonic, sodaBase);
|
|
96
|
+
|
|
97
|
+
// 3. Execute. srcChainKey is the hub.
|
|
98
|
+
const result = await sodax.bridge.bridge({
|
|
99
|
+
params: {
|
|
100
|
+
srcChainKey: ChainKeys.SONIC_MAINNET,
|
|
101
|
+
srcAddress: (await evmWp.getWalletAddress()) as `0x${string}`,
|
|
102
|
+
srcToken: sodaSonic.address,
|
|
103
|
+
amount: parseUnits('1', sodaSonic.decimals),
|
|
104
|
+
dstChainKey: ChainKeys.BASE_MAINNET,
|
|
105
|
+
dstToken: sodaBase.address,
|
|
106
|
+
recipient: recipientOnBase,
|
|
107
|
+
},
|
|
108
|
+
raw: false,
|
|
109
|
+
walletProvider: evmWp,
|
|
110
|
+
});
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Internally `bridge()` branches on `isHubChainKeyType(srcChainKey)` and uses the user's hub wallet abstraction as the spender (the assetManager spoke address is used for non-hub sources). For allowance and approval flows, treat Sonic-as-source the same as any other EVM source — `isAllowanceValid` and `approve` use the same parameter shape.
|
|
114
|
+
|
|
79
115
|
### Bridgeable-amount check
|
|
80
116
|
|
|
81
117
|
Respects vault deposit limits (spoke→hub) and asset-manager balance (hub→spoke). Pass the source and destination tokens as full `XToken` objects (each carries its own `chainKey`):
|
|
@@ -111,7 +147,7 @@ if (result.ok) {
|
|
|
111
147
|
| Method | Success type |
|
|
112
148
|
|---|---|
|
|
113
149
|
| `bridge` | `TxHashPair` |
|
|
114
|
-
| `createBridgeIntent` | `
|
|
150
|
+
| `createBridgeIntent` | `IntentTxResult<K, Raw>` = `{ tx: TxReturnType<K, Raw>, relayData }` |
|
|
115
151
|
| `approve` | `TxReturnType<K, Raw>` |
|
|
116
152
|
| `isAllowanceValid` | `boolean` |
|
|
117
153
|
| `getBridgeableAmount` | `BridgeLimit = { amount, decimals, type }` |
|
|
@@ -133,4 +169,5 @@ if (result.ok) {
|
|
|
133
169
|
|
|
134
170
|
- v1 → v2 bridge migration: [`features/bridge.md`](../../../migration-v1-to-v2/knowledge/features/bridge.md).
|
|
135
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).
|
|
136
173
|
- Hub-and-spoke vault architecture: [`../architecture.md`](../architecture.md) § 1.
|