@sodax/skills 2.0.0-rc.19 → 2.0.0-rc.20
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/package.json +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +2 -2
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +1 -1
- package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +1 -1
- package/skills/sodax-sdk/SKILL.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/architecture.md +6 -6
- package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +22 -2
- package/skills/sodax-sdk/integration/knowledge/features/money-market.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +11 -6
- package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +27 -0
- package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +5 -4
- package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +7 -6
- package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +1 -0
- package/skills/sodax-wallet-sdk-core/evm/SKILL.md +3 -3
- package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
- package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
- package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +4 -4
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +2 -2
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
package/package.json
CHANGED
|
@@ -89,7 +89,7 @@ await submitSwapTx({ request, apiConfig: { baseURL: 'https://...' } });
|
|
|
89
89
|
```ts
|
|
90
90
|
// @ai-snippets-skip
|
|
91
91
|
const { data: status } = useSwapsApiSubmitTxStatus({ params: { txHash, srcChainKey } });
|
|
92
|
-
// status?.data?.status: 'pending' | 'relaying' | 'relayed' | 'posting_execution' | '
|
|
92
|
+
// status?.data?.status: 'pending' | 'relaying' | 'relayed' | 'posting_execution' | 'posted_execution' | 'solved' | 'failed'
|
|
93
93
|
```
|
|
94
94
|
|
|
95
95
|
> The full `useSwapsApi*` hook list (with polling + types) is in [hooks-index.md](../reference/hooks-index.md); key shapes in [querykey-conventions.md](../reference/querykey-conventions.md). For non-React callers, `sodax.api.swaps` is documented in the `sodax-sdk` skill (integration mode).
|
|
@@ -207,7 +207,7 @@ The underlying SDK methods (`isStorageRegistered` / `registerStorage` on the NEA
|
|
|
207
207
|
| Hook | Polling | Notes |
|
|
208
208
|
|---|---|---|
|
|
209
209
|
| `useBackendIntentByTxHash` | 1s | once a `txHash` is supplied (refetch is unconditional, not "while pending") |
|
|
210
|
-
| `useSwapsApiSubmitTxStatus` | 1s | requires `txHash` + `srcChainKey`; stops on `
|
|
210
|
+
| `useSwapsApiSubmitTxStatus` | 1s | requires `txHash` + `srcChainKey`; stops on `solved` / `failed` |
|
|
211
211
|
| `useSwapsApiStatus` | 1s | solver intent status; stops on status `3` / `4` |
|
|
212
212
|
| `useBackendOrderbook` | none | `staleTime: 30s` — fresh-window, no background refetch |
|
|
213
213
|
| `useExpiredUtxos` (bitcoin) | 60s | refetchInterval |
|
|
@@ -151,7 +151,7 @@ function SubmitButton({ request, baseURL }: { request: SubmitTxRequestV2; baseUR
|
|
|
151
151
|
}
|
|
152
152
|
```
|
|
153
153
|
|
|
154
|
-
Poll the processing status with `useSwapsApiSubmitTxStatus` — it requires **both** `txHash` and `srcChainKey` (the v2 status endpoint needs the source chain key) and stops polling on `
|
|
154
|
+
Poll the processing status with `useSwapsApiSubmitTxStatus` — it requires **both** `txHash` and `srcChainKey` (the v2 status endpoint needs the source chain key) and stops polling on `solved` / `failed`:
|
|
155
155
|
|
|
156
156
|
```tsx
|
|
157
157
|
import { useSwapsApiSubmitTxStatus } from '@sodax/dapp-kit';
|
|
@@ -167,6 +167,6 @@ function SwapStatus({ txHash, srcChainKey }: { txHash: string; srcChainKey: stri
|
|
|
167
167
|
| Hook | Interval |
|
|
168
168
|
|------|---------|
|
|
169
169
|
| `useBackendIntentByTxHash` | 1s |
|
|
170
|
-
| `useSwapsApiSubmitTxStatus` | 1s (stops on `
|
|
170
|
+
| `useSwapsApiSubmitTxStatus` | 1s (stops on `solved` / `failed`) |
|
|
171
171
|
| `useBackendOrderbook` | none (`staleTime: 30s`, no auto-refetch) |
|
|
172
172
|
| Others | No auto-refresh |
|
|
@@ -162,7 +162,7 @@ ChainKeys.INJECTIVE_MAINNET; // 'injective-1'
|
|
|
162
162
|
ChainKeys.NEAR_MAINNET; // 'near'
|
|
163
163
|
ChainKeys.STACKS_MAINNET; // 'stacks'
|
|
164
164
|
ChainKeys.BITCOIN_MAINNET; // 'bitcoin'
|
|
165
|
-
// HyperEVM, Lightlink, Redbelly, Kaia also available.
|
|
165
|
+
// HyperEVM, Lightlink, Redbelly, Kaia, Hedera also available.
|
|
166
166
|
```
|
|
167
167
|
|
|
168
168
|
**v1 → v2:** the legacy `*_MAINNET_CHAIN_ID` constants (e.g. `BSC_MAINNET_CHAIN_ID`) are gone. Use `ChainKeys.X_MAINNET` namespace access.
|
|
@@ -191,7 +191,7 @@ Typed React Query wrappers over the backend Swaps API v2 (`sodax.api.swaps.*`),
|
|
|
191
191
|
| `useSwapsApiIntentExtraData` | Query; relay extra-data for submit |
|
|
192
192
|
| `useSwapsApiFilledIntent` | Query; on-chain fill state by tx hash |
|
|
193
193
|
| `useSwapsApiIntent` | Query; decoded intent struct by tx hash |
|
|
194
|
-
| `useSwapsApiSubmitTxStatus` | Query (1s); requires `txHash` + `srcChainKey`; polls until `
|
|
194
|
+
| `useSwapsApiSubmitTxStatus` | Query (1s); requires `txHash` + `srcChainKey`; polls until `solved` / `failed` |
|
|
195
195
|
|
|
196
196
|
### Actions (mutations)
|
|
197
197
|
|
|
@@ -131,7 +131,7 @@ If your dapp-kit consumer code catches errors from mutations and uses `instanceo
|
|
|
131
131
|
+ }
|
|
132
132
|
```
|
|
133
133
|
|
|
134
|
-
`isSodaxError` is re-exported from `@sodax/dapp-kit`. Discriminate via `(error.feature, error.code)` — the feature is now a first-class field, and the code vocabulary is unified to
|
|
134
|
+
`isSodaxError` is re-exported from `@sodax/dapp-kit`. Discriminate via `(error.feature, error.code)` — the feature is now a first-class field, and the code vocabulary is unified to 14 reason-only codes (`'USER_REJECTED'` is reachable from any orchestrator that wraps a wallet sign step, which lets consumers render a "Cancelled" UI distinct from real failures).
|
|
135
135
|
|
|
136
136
|
Full SDK-level detail: `sodax-sdk`: `migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md`.
|
|
137
137
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-sdk
|
|
3
|
-
description: 'Integrate SODAX cross-chain DeFi into a backend, Node script, bot, indexer, or non-React app with @sodax/sdk — swaps, lending/borrowing, staking, bridging, concentrated-liquidity DEX, ICX/bnUSD/BALN token migration, partner fees, and stuck-asset recovery across Sonic (hub) +
|
|
3
|
+
description: 'Integrate SODAX cross-chain DeFi into a backend, Node script, bot, indexer, or non-React app with @sodax/sdk — swaps, lending/borrowing, staking, bridging, concentrated-liquidity DEX, ICX/bnUSD/BALN token migration, partner fees, and stuck-asset recovery across Sonic (hub) + 20 spoke chains. INTEGRATION (write NEW v2 code) — hub-and-spoke architecture across EVM and non-EVM chains; covers intent-based swaps, lending/borrowing (money market), staking, bridging, concentrated-liquidity DEX, token migration, partner fees, and stuck-asset recovery. Use whenever a non-React or backend codebase calls `@sodax/sdk` directly (Node scripts, indexers, bots, server APIs, custom non-React browser flows). Triggers on "use @sodax/sdk", "swap with Sodax", "Sodax bridge", "Sodax money market", "Sodax staking", "cross-chain DeFi", "Sonic hub", any `Sodax` / `ChainKeys` / `Result<T>` / `SodaxError` symbol. For React dapps, prefer `sodax-dapp-kit` instead. MIGRATION (port v1 → v2) — the v2 reshape replaced `*SpokeProvider` classes with chain-key-driven routing, throws with `Result<T>`, module-specific error unions with `SodaxError<C>`, ad-hoc wallet/raw branching with `WalletProviderSlot<K, Raw>`, and static lookup tables with `ConfigService`. Triggers on "migrate Sodax v1", "upgrade @sodax/sdk", "v1 → v2", "useSpokeProvider broken", "Sodax error types changed", v1 fingerprints (`_MAINNET_CHAIN_ID`, `*SpokeProvider`, `xChainId`, `SpokeChainId`, `MoneyMarketError`/`IntentError`/`StakingError`/`BridgeError`/`MigrationError`/`AssetServiceError`/`ConcentratedLiquidityError`/`RelayError`). Load this skill if EITHER applies; the body gates by mode.'
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
6
|
version: '0.0.1'
|
|
@@ -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
|
|
@@ -137,13 +137,13 @@ new Sodax(config?: SodaxOptions): Sodax;
|
|
|
137
137
|
|
|
138
138
|
`SodaxDefaultConfig` has exactly **10 fields** (all required at the type level, but `DeepPartial` makes every leaf optional):
|
|
139
139
|
|
|
140
|
-
- `chains: Record<SpokeChainKey, SpokeChainConfig>` — per-spoke-chain config. Each entry carries `rpcUrl`, polling config, and chain-family-specific extras (`BitcoinSpokeChainConfig`, `StellarSpokeChainConfig`, etc.).
|
|
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
141
|
- `swaps: SwapsConfig` — supported solver tokens per chain (+ optional per-feature `partnerFee` override).
|
|
142
142
|
- `moneyMarket: MoneyMarketConfig` — money market contracts + supported tokens (+ optional per-feature `partnerFee` override).
|
|
143
143
|
- `bridge: BridgeConfig` — bridge `{ partnerFee }` override.
|
|
144
144
|
- `dex: DexConfig` — DEX pool/asset config.
|
|
145
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.
|
|
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
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.
|
|
148
148
|
- `solver: SolverConfig` — `{ intentsContract, solverApiEndpoint, protocolIntentsContract }`.
|
|
149
149
|
- `relay: RelayConfig` — intent relay endpoint + chain-id map.
|
|
@@ -385,7 +385,7 @@ Public methods declare narrow code unions via `Extract<SodaxErrorCode, ...>`:
|
|
|
385
385
|
```ts
|
|
386
386
|
type CreateSupplyIntentErrorCode = Extract<
|
|
387
387
|
SodaxErrorCode,
|
|
388
|
-
'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN'
|
|
388
|
+
'USER_REJECTED' | 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN'
|
|
389
389
|
>;
|
|
390
390
|
```
|
|
391
391
|
|
|
@@ -1,9 +1,15 @@
|
|
|
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
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.
|
|
@@ -12,6 +18,20 @@ EVM chains (12 of them) work uniformly through `IEvmWalletProvider`. Non-EVM cha
|
|
|
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.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Money Market — `MoneyMarketService`
|
|
2
2
|
|
|
3
|
-
Cross-chain lending and borrowing. Supply, borrow, withdraw, repay across
|
|
3
|
+
Cross-chain lending and borrowing. Supply, borrow, withdraw, repay across 21 spoke chains. Position state lives on the hub.
|
|
4
4
|
|
|
5
5
|
Access: `sodax.moneyMarket`. Service class: `MoneyMarketService`. Feature tag for errors: `'moneyMarket'`.
|
|
6
6
|
|
|
@@ -9,8 +9,13 @@ response is validated at runtime against a valibot schema, so a backend contract
|
|
|
9
9
|
Access: `sodax.api.swaps`. Service class: `SwapsApiService`. **Errors:** every failure (network, timeout,
|
|
10
10
|
non-2xx HTTP, or response-shape mismatch) returns `Result<T, SodaxError<'EXTERNAL_API_ERROR'>>` with
|
|
11
11
|
`feature: 'backend'`, `context.api: 'swaps'`, and `context.endpoint` (the path). The underlying failure
|
|
12
|
-
is preserved on `error.cause
|
|
13
|
-
|
|
12
|
+
is preserved on `error.cause` — a `SwapsApiError` from the `@sodax/swaps-api` client this service wraps
|
|
13
|
+
(read its `code`: `NETWORK_ERROR` | `TIMEOUT_ERROR` | `HTTP_ERROR` | `PARSE_ERROR` | `VALIDATION_ERROR`;
|
|
14
|
+
the same code is mirrored on `error.context.code`, and both `SwapsApiError` and the `SwapsApiErrorCode`
|
|
15
|
+
union are re-exported from `@sodax/sdk`). Idempotent
|
|
16
|
+
reads/polls (and pure-compute POSTs like `getQuote`) retry transient failures; mutating calls do not.
|
|
17
|
+
This differs from the feature services (`sodax.swaps`, etc.), whose errors carry their own `feature`
|
|
18
|
+
(`'swap'`, …) — the swaps **HTTP client** is uniformly `feature: 'backend'`.
|
|
14
19
|
|
|
15
20
|
## Methods
|
|
16
21
|
|
|
@@ -103,8 +108,8 @@ if (!submit.ok) return;
|
|
|
103
108
|
|
|
104
109
|
// Both txHash AND srcChainKey are required by the status endpoint.
|
|
105
110
|
const status = await sodax.api.swaps.getSubmitTxStatus({ txHash, srcChainKey });
|
|
106
|
-
if (status.ok && status.value.data.status === '
|
|
107
|
-
// Lifecycle: 'pending' → 'relaying' → 'relayed' → 'posting_execution' → '
|
|
111
|
+
if (status.ok && status.value.data.status === 'solved') { /* settled */ }
|
|
112
|
+
// Lifecycle: 'pending' → 'relaying' → 'relayed' → 'posting_execution' → 'posted_execution' → 'solved' | 'failed'.
|
|
108
113
|
```
|
|
109
114
|
|
|
110
115
|
## Status fields — three distinct `status` values (don't conflate)
|
|
@@ -113,9 +118,9 @@ if (status.ok && status.value.data.status === 'executed') { /* settled */ }
|
|
|
113
118
|
|---|---|---|---|
|
|
114
119
|
| `getStatus` | `StatusResponseV2.status` | **number** (`SwapIntentStatusCodeV2`) | `-1` NOT_FOUND · `1` NOT_STARTED_YET · `2` STARTED_NOT_FINISHED · `3` SOLVED (terminal) · `4` FAILED (terminal). `fillTxHash` is set only when `status === 3`. |
|
|
115
120
|
| `submitTx` | `SubmitTxResponseV2.data.status` | string | `'inserted'` (new) or `'duplicate'` (already submitted — submit-tx is idempotent on `(txHash, srcChainKey)`). |
|
|
116
|
-
| `getSubmitTxStatus` | `SubmitTxStatusResponseV2.data.status` | string | `'pending'` / `'relaying'` / `'relayed'` / `'posting_execution'` / `'
|
|
121
|
+
| `getSubmitTxStatus` | `SubmitTxStatusResponseV2.data.status` | string | `'pending'` / `'relaying'` / `'relayed'` / `'posting_execution'` / `'posted_execution'` / `'solved'` / `'failed'` (`'solved'` / `'failed'` terminal). |
|
|
117
122
|
|
|
118
|
-
`getStatus` reports the **solver** intent status as a numeric code; the two submit-tx calls report **string** statuses (submission result vs relay-processing lifecycle). They are unrelated — don't treat one as the other
|
|
123
|
+
`getStatus` reports the **solver** intent status as a numeric code (`3` = `SOLVED`); the two submit-tx calls report **string** statuses (submission result vs relay-processing lifecycle, whose success terminal is the string `'solved'`). They are unrelated — don't treat one as the other; note the numeric solver `SOLVED` (`3`) is distinct from the submit-tx string `'solved'`.
|
|
119
124
|
|
|
120
125
|
## Per-call overrides
|
|
121
126
|
|
|
@@ -41,6 +41,33 @@ const sodax = new Sodax(config);
|
|
|
41
41
|
await sodax.config.initialize();
|
|
42
42
|
```
|
|
43
43
|
|
|
44
|
+
### Hub RPC failover (multiple endpoints)
|
|
45
|
+
|
|
46
|
+
The Sonic hub is read through two clients — the hub provider (wallet-address lookups, contract reads) and the Sonic spoke service (hub-chain allowance checks, gas estimation, intent creation). Each accepts an ordered `rpcUrls` list, wrapped internally in a viem `fallback()` transport that advances to the next endpoint on 5xx/52x/transport errors. The single `rpcUrl` stays the default; `rpcUrls` is opt-in and, when set and non-empty, takes precedence (first entry is primary). Optional `rpcOptions` tunes the fallback (`rank` / `retryCount` / `retryDelay`).
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
import { Sodax, ChainKeys, type SodaxOptions } from '@sodax/sdk';
|
|
50
|
+
|
|
51
|
+
const SONIC_RPCS = ['https://rpc.soniclabs.com', 'https://sonic-backup.example.com'];
|
|
52
|
+
|
|
53
|
+
const config: SodaxOptions = {
|
|
54
|
+
// Hub provider failover.
|
|
55
|
+
hub: {
|
|
56
|
+
rpcUrls: SONIC_RPCS,
|
|
57
|
+
rpcOptions: { retryCount: 3 }, // optional viem fallback() tuning
|
|
58
|
+
},
|
|
59
|
+
// Sonic spoke failover — same physical chain, separate client/knob.
|
|
60
|
+
chains: {
|
|
61
|
+
[ChainKeys.SONIC_MAINNET]: { rpcUrls: SONIC_RPCS },
|
|
62
|
+
},
|
|
63
|
+
};
|
|
64
|
+
|
|
65
|
+
const sodax = new Sodax(config);
|
|
66
|
+
await sodax.config.initialize();
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
> Both knobs target the same physical chain (Sonic) but back distinct clients, so set **both** for end-to-end hub resilience — `hub.rpcUrls` covers the hub provider and `chains.[SONIC_MAINNET].rpcUrls` covers the swap/intent path. Omit them to keep the single-endpoint default (fully backward compatible). The endpoint list is read once at `new Sodax(...)` time.
|
|
70
|
+
|
|
44
71
|
### Lazy initialization
|
|
45
72
|
|
|
46
73
|
`config.initialize()` is idempotent — calling it twice is a no-op. The first call fetches; subsequent calls return cached data. Treat it as "make sure config is loaded before any feature method".
|
|
@@ -31,7 +31,7 @@ const { tx, intent, relayData } = result.value;
|
|
|
31
31
|
When you know the method, the narrow code union from its declaration enables an exhaustive switch:
|
|
32
32
|
|
|
33
33
|
```ts
|
|
34
|
-
type CreateSupplyIntentErrorCode = 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN';
|
|
34
|
+
type CreateSupplyIntentErrorCode = 'USER_REJECTED' | 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN';
|
|
35
35
|
|
|
36
36
|
const result = await sodax.moneyMarket.createSupplyIntent({ params, raw: true });
|
|
37
37
|
if (!result.ok) {
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Chain keys
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
21 supported chains. The `ChainKey` type is the union of every `ChainKeys.*` value. **`SpokeChainKey` is the same union — it includes Sonic.** The "spoke" naming refers to how feature services type their `srcChainKey` parameter (they accept the hub too — bridge / swap / staking etc. all run from Sonic as source via the hub-wallet abstraction). When you specifically need "EVM chains excluding the hub" use `EVM_SPOKE_ONLY_CHAIN_KEYS` / `isEvmSpokeOnlyChainKeyType`.
|
|
4
4
|
|
|
5
5
|
| `ChainKeys.*` | String value | Family | Hub vs spoke | Address type |
|
|
6
6
|
|---|---|---|---|---|
|
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
| `LIGHTLINK_MAINNET` | `'lightlink'` | EVM | spoke | `0x${string}` |
|
|
17
17
|
| `REDBELLY_MAINNET` | `'redbelly'` | EVM | spoke | `0x${string}` |
|
|
18
18
|
| `KAIA_MAINNET` | `'0x2019.kaia'` | EVM | spoke | `0x${string}` |
|
|
19
|
+
| `HEDERA_MAINNET` | `'hedera'` | EVM | spoke | `0x${string}` |
|
|
19
20
|
| `SOLANA_MAINNET` | `'solana'` | SOLANA | spoke | base58 PublicKey string |
|
|
20
21
|
| `SUI_MAINNET` | `'sui'` | SUI | spoke | `0x${string}` (32-byte) |
|
|
21
22
|
| `STELLAR_MAINNET` | `'stellar'` | STELLAR | spoke | `G…` |
|
|
@@ -35,9 +36,9 @@
|
|
|
35
36
|
|
|
36
37
|
| Type | What it is |
|
|
37
38
|
|---|---|
|
|
38
|
-
| `ChainKey` | Union of all `ChainKeys.*` values (
|
|
39
|
-
| `SpokeChainKey` |
|
|
40
|
-
| `EvmChainKey` | Subset of `ChainKey` for the
|
|
39
|
+
| `ChainKey` | Union of all `ChainKeys.*` values (21 chains). |
|
|
40
|
+
| `SpokeChainKey` | Same union as `ChainKey` — includes Sonic (21 chains). For "EVM chains excluding the hub" use `EvmSpokeOnlyChainKey`. |
|
|
41
|
+
| `EvmChainKey` | Subset of `ChainKey` for the 13 EVM chains. |
|
|
41
42
|
| `HubChainKey` | The literal `'sonic'`. |
|
|
42
43
|
|
|
43
44
|
### Chain-family helpers
|
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
# Error codes
|
|
2
2
|
|
|
3
|
-
All
|
|
3
|
+
All 14 codes the SDK can emit. Each error is `SodaxError<C>` where `C` is one of these. The producing feature is on `error.feature`.
|
|
4
4
|
|
|
5
5
|
| Code | Meaning | Common `error.context` fields | Retry advice |
|
|
6
6
|
|---|---|---|---|
|
|
7
|
+
| `USER_REJECTED` | User cancelled the wallet prompt (signing / approval / connection). Classified at the source by `intentCreationFailed` / `approveFailed` wrappers via a built-in detector that recognises viem `4001` / `UserRejectedRequestError`, ICON Hana `CANCEL_SIGNING` / `-31002`, and name + message patterns from Solana / Sui / Stellar / Stacks / NEAR / Injective wallets. | `phase` (set to whichever phase the wrapper was wrapping: `'intentCreation'` or `'approve'`), `action` | No — user-initiated. Render a "Cancelled" UI, not a failure. |
|
|
7
8
|
| `VALIDATION_FAILED` | Pre-flight invariant tripped (input shape, unsupported chain, etc.). | `field`, `reason`, `phase: 'validate'` | No — fix the input. |
|
|
8
9
|
| `INTENT_CREATION_FAILED` | Building the intent / payload failed. | `phase: 'intentCreation'`, `action` | Sometimes — depends on root cause (`error.cause`). |
|
|
9
10
|
| `EXECUTION_FAILED` | Orchestrator-level catch-all (multi-step op didn't complete). | `action`, `phase: 'execution'` or `'postExecution'` | Sometimes — inspect cause. |
|
|
@@ -77,10 +78,10 @@ Narrow code unions per public method. Use these for exhaustive `switch` discrimi
|
|
|
77
78
|
|
|
78
79
|
```ts
|
|
79
80
|
// 'create*Intent' methods
|
|
80
|
-
type CreateIntentErrorCode = 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN';
|
|
81
|
+
type CreateIntentErrorCode = 'USER_REJECTED' | 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN';
|
|
81
82
|
|
|
82
83
|
// 'approve' methods
|
|
83
|
-
type ApproveErrorCode = 'VALIDATION_FAILED' | 'APPROVE_FAILED' | 'UNKNOWN';
|
|
84
|
+
type ApproveErrorCode = 'USER_REJECTED' | 'VALIDATION_FAILED' | 'APPROVE_FAILED' | 'UNKNOWN';
|
|
84
85
|
|
|
85
86
|
// 'isAllowanceValid' methods
|
|
86
87
|
type AllowanceCheckErrorCode = 'VALIDATION_FAILED' | 'ALLOWANCE_CHECK_FAILED' | 'UNKNOWN';
|
|
@@ -97,7 +98,7 @@ type LookupErrorCode = 'VALIDATION_FAILED' | 'LOOKUP_FAILED' | 'UNKNOWN';
|
|
|
97
98
|
| Method | Narrow code union |
|
|
98
99
|
|---|---|
|
|
99
100
|
| `createIntent` | `CreateIntentErrorCode` |
|
|
100
|
-
| `swap` | All of {`VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `EXECUTION_FAILED`, `TX_VERIFICATION_FAILED`, `TX_SUBMIT_FAILED`, `RELAY_TIMEOUT`, `RELAY_FAILED`, `EXTERNAL_API_ERROR`, `UNKNOWN`} |
|
|
101
|
+
| `swap` | All of {`USER_REJECTED`, `VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `EXECUTION_FAILED`, `TX_VERIFICATION_FAILED`, `TX_SUBMIT_FAILED`, `RELAY_TIMEOUT`, `RELAY_FAILED`, `EXTERNAL_API_ERROR`, `UNKNOWN`} |
|
|
101
102
|
| `postExecution` | `EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` (with `phase: 'postExecution'`) |
|
|
102
103
|
| `createLimitOrder`, `createLimitOrderIntent` | `CreateIntentErrorCode` |
|
|
103
104
|
| `cancelIntent`, `cancelLimitOrder` | `EXECUTION_FAILED \| VALIDATION_FAILED \| UNKNOWN` |
|
|
@@ -106,7 +107,7 @@ type LookupErrorCode = 'VALIDATION_FAILED' | 'LOOKUP_FAILED' | 'UNKNOWN';
|
|
|
106
107
|
|
|
107
108
|
| Method | Narrow code union |
|
|
108
109
|
|---|---|
|
|
109
|
-
| `supply`, `borrow`, `withdraw`, `repay` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| EXECUTION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| UNKNOWN` (with `action` discriminator) |
|
|
110
|
+
| `supply`, `borrow`, `withdraw`, `repay` | `USER_REJECTED \| VALIDATION_FAILED \| INTENT_CREATION_FAILED \| EXECUTION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| UNKNOWN` (with `action` discriminator) |
|
|
110
111
|
| `createSupplyIntent`, `createBorrowIntent`, `createWithdrawIntent`, `createRepayIntent` | `CreateIntentErrorCode` |
|
|
111
112
|
| `approve` | `ApproveErrorCode` |
|
|
112
113
|
| `isAllowanceValid` | `AllowanceCheckErrorCode` |
|
|
@@ -157,7 +158,7 @@ type LookupErrorCode = 'VALIDATION_FAILED' | 'LOOKUP_FAILED' | 'UNKNOWN';
|
|
|
157
158
|
|
|
158
159
|
### Partner (`feature: 'partner'`) and Recovery (`feature: 'recovery'`)
|
|
159
160
|
|
|
160
|
-
Both follow the same shape: action methods get the full exec union (`'EXECUTION_FAILED' \| 'INTENT_CREATION_FAILED' \| ...`), read methods get `LookupErrorCode`, approve methods get `ApproveErrorCode
|
|
161
|
+
Both follow the same shape: action methods get the full exec union (`'EXECUTION_FAILED' \| 'INTENT_CREATION_FAILED' \| ...`), read methods get `LookupErrorCode`, approve methods get `ApproveErrorCode` (so partner's `approve` can emit `'USER_REJECTED'`).
|
|
161
162
|
|
|
162
163
|
### Backend / Swaps API (`feature: 'backend'`)
|
|
163
164
|
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
| **Hub wallet abstraction** | A user-specific contract on the hub that holds funds during cross-chain ops. Resolved via `EvmHubProvider.getUserHubWalletAddress(...)`. |
|
|
18
18
|
| **`Result<T>`** | The `{ ok: true; value: T } \| { ok: false; error: E }` discriminated union returned by every async public method. |
|
|
19
19
|
| **`SodaxError<C>`** | The canonical error class. Discriminated by `(feature, code)`. |
|
|
20
|
-
| **Code (`SodaxErrorCode`)** | One of
|
|
20
|
+
| **Code (`SodaxErrorCode`)** | One of 14 reason-only error codes. See § 3. |
|
|
21
21
|
| **Feature (`SodaxFeature`)** | One of 9 domain features (`'swap'`, `'moneyMarket'`, …, `'leverageYield'`) plus `'backend'` for the HTTP-client layer (`BackendApiService` / `sodax.api.swaps`). |
|
|
22
22
|
| **Phase (`SodaxPhase`)** | The orchestration step at which an error occurred. See § 3. |
|
|
23
23
|
| **Action (`error.context.action`)** | The user-facing operation that triggered the error (`'supply'`, `'stake'`, `'migrateBaln'`, …). |
|
|
@@ -216,7 +216,7 @@ Every public method declares a `<MethodName>ErrorCode` narrow union built via `E
|
|
|
216
216
|
```ts
|
|
217
217
|
type CreateSupplyIntentErrorCode = Extract<
|
|
218
218
|
SodaxErrorCode,
|
|
219
|
-
'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN'
|
|
219
|
+
'USER_REJECTED' | 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN'
|
|
220
220
|
>;
|
|
221
221
|
|
|
222
222
|
// In the queryFn or call site:
|
|
@@ -47,6 +47,7 @@ v1 exported one constant per chain (`SONIC_MAINNET_CHAIN_ID`, `ARBITRUM_MAINNET_
|
|
|
47
47
|
| `BASE_MAINNET_CHAIN_ID` | `ChainKeys.BASE_MAINNET` | `'0x2105.base'` |
|
|
48
48
|
| `BSC_MAINNET_CHAIN_ID` | `ChainKeys.BSC_MAINNET` | `'0x38.bsc'` |
|
|
49
49
|
| `ETHEREUM_MAINNET_CHAIN_ID` | `ChainKeys.ETHEREUM_MAINNET` | `'ethereum'` |
|
|
50
|
+
| `HEDERA_MAINNET_CHAIN_ID` | `ChainKeys.HEDERA_MAINNET` | `'hedera'` |
|
|
50
51
|
| `HYPEREVM_MAINNET_CHAIN_ID` | `ChainKeys.HYPEREVM_MAINNET` | `'hyper'` |
|
|
51
52
|
| `ICON_MAINNET_CHAIN_ID` | `ChainKeys.ICON_MAINNET` | `'0x1.icon'` |
|
|
52
53
|
| `INJECTIVE_MAINNET_CHAIN_ID` | `ChainKeys.INJECTIVE_MAINNET` | `'injective-1'` |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sodax-wallet-sdk-core-evm
|
|
3
|
-
description: 'Granular skill for the @sodax/wallet-sdk-core v2 EVM wallet provider only — `EvmWalletProvider` (backed by viem), one class covering all
|
|
3
|
+
description: 'Granular skill for the @sodax/wallet-sdk-core v2 EVM wallet provider only — `EvmWalletProvider` (backed by viem), one class covering all 13 SODAX EVM chains — the Sonic hub plus 12 EVM spoke chains (Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera). Use when a backend / Node script / CI / bot / non-React browser flow needs to instantiate an EVM provider directly and sign + broadcast — e.g. "instantiate EvmWalletProvider", "private-key EVM signing in Node", "EVM wallet provider for a bot", "sendTransaction from a script". Covers BOTH integration (write new v2 code) and migration (port v1 — almost a no-op at this surface: deep-import → barrel). Picks via Step 1. Links into the parent sodax-wallet-sdk-core knowledge tree. For React dapps use the sodax-wallet-sdk-react skill instead (get the typed provider via useWalletProvider).'
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
6
|
version: '0.0.1'
|
|
@@ -9,13 +9,13 @@ metadata:
|
|
|
9
9
|
|
|
10
10
|
# EVM (`wallet-sdk-core` granular skill)
|
|
11
11
|
|
|
12
|
-
Granular skill for `EvmWalletProvider` — the low-level EVM wallet for backend / Node / non-React flows. One class covers all
|
|
12
|
+
Granular skill for `EvmWalletProvider` — the low-level EVM wallet for backend / Node / non-React flows. One class covers all 13 SODAX EVM chains — the Sonic hub plus 12 EVM spoke chains — via `getEvmViemChain()`. Source-of-truth reference lives in the parent broad skill's knowledge tree; this file is the focused workflow only.
|
|
13
13
|
|
|
14
14
|
## Step 1 — Clarify with user before coding
|
|
15
15
|
|
|
16
16
|
1. **New code or v1 → v2 port?** New → § Integration. Port v1 → § Migration (almost always a no-op here).
|
|
17
17
|
2. **Private-key or browser-extension config?** EVM discriminates by **field presence** (no `type`): PK = `{ privateKey, chainId, rpcUrl? }` (Node / CI / bots); browser-extension = `{ walletClient, publicClient }` (pre-built by wagmi / the consumer). Mutually exclusive — pick one.
|
|
18
|
-
3. **Which chain?** One `EvmWalletProvider` covers all
|
|
18
|
+
3. **Which chain?** One `EvmWalletProvider` covers all 13 EVM chains (the Sonic hub plus 12 EVM spokes) via `chainId: EvmChainKey` (`ChainKeys.SONIC_MAINNET`, …).
|
|
19
19
|
|
|
20
20
|
## Integration workflow (new v2 code)
|
|
21
21
|
|
|
@@ -18,7 +18,7 @@ It is intentionally framework-agnostic — Node ≥ 20.12, browser, edge runtime
|
|
|
18
18
|
|
|
19
19
|
| Chain family | Provider class | Underlying chain SDK |
|
|
20
20
|
|---|---|---|
|
|
21
|
-
| EVM (
|
|
21
|
+
| EVM (13 chains) | `EvmWalletProvider` | `viem` |
|
|
22
22
|
| Solana | `SolanaWalletProvider` | `@solana/web3.js` |
|
|
23
23
|
| Sui | `SuiWalletProvider` | `@mysten/sui` + `@mysten/wallet-standard` |
|
|
24
24
|
| Bitcoin | `BitcoinWalletProvider` | `bitcoinjs-lib` (+ `ecpair`, `secp256k1`) |
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# EVM — `EvmWalletProvider`
|
|
2
2
|
|
|
3
|
-
Backed by [viem](https://viem.sh). One class covers
|
|
3
|
+
Backed by [viem](https://viem.sh). One class covers **every** SODAX EVM spoke chain via `getEvmViemChain()` (see the table below).
|
|
4
4
|
|
|
5
5
|
| | |
|
|
6
6
|
|---|---|
|
|
@@ -8,7 +8,7 @@ Backed by [viem](https://viem.sh). One class covers all **12** SODAX EVM spoke c
|
|
|
8
8
|
| Interface | `IEvmWalletProvider` (from `@sodax/types`) |
|
|
9
9
|
| Discriminant style | **Field presence** (no `type` field) |
|
|
10
10
|
| Underlying SDK | `viem` |
|
|
11
|
-
| Supported chains | Sonic (hub), Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia |
|
|
11
|
+
| Supported chains | Sonic (hub), Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera |
|
|
12
12
|
|
|
13
13
|
---
|
|
14
14
|
|
|
@@ -4,7 +4,7 @@ Chain families and spoke chain keys this package can sign for. Keys live in `@so
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
## EVM (one provider,
|
|
7
|
+
## EVM (one provider, 13 chains)
|
|
8
8
|
|
|
9
9
|
`EvmWalletProvider` covers every EVM spoke chain via `getEvmViemChain()`. The provider is exhaustive — adding a new `EvmChainKey` to `@sodax/types` requires updating `getEvmViemChain` (caught at compile time via a `never` assertion in the default branch).
|
|
10
10
|
|
|
@@ -22,6 +22,7 @@ Chain families and spoke chain keys this package can sign for. Keys live in `@so
|
|
|
22
22
|
| `ChainKeys.LIGHTLINK_MAINNET` | `lightlinkPhoenix` |
|
|
23
23
|
| `ChainKeys.REDBELLY_MAINNET` | `redbellyMainnet` |
|
|
24
24
|
| `ChainKeys.KAIA_MAINNET` | `kaia` |
|
|
25
|
+
| `ChainKeys.HEDERA_MAINNET` | `hedera` |
|
|
25
26
|
|
|
26
27
|
---
|
|
27
28
|
|
|
@@ -38,7 +39,7 @@ Chain families and spoke chain keys this package can sign for. Keys live in `@so
|
|
|
38
39
|
| NEAR | `NearWalletProvider` | `ChainKeys.NEAR_MAINNET` |
|
|
39
40
|
| Stacks | `StacksWalletProvider` | `ChainKeys.STACKS_MAINNET` |
|
|
40
41
|
|
|
41
|
-
>
|
|
42
|
+
> 21 spoke chains total = 13 EVM + 8 non-EVM. The hub chain (Sonic) is counted with EVM.
|
|
42
43
|
|
|
43
44
|
---
|
|
44
45
|
|
|
@@ -90,7 +90,7 @@ You should **not** read the store directly. Use the public hooks. The store hook
|
|
|
90
90
|
|
|
91
91
|
For EVM, available wallets are discovered via [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) — browser extensions broadcast their metadata and `useXConnectors({ xChainType: 'EVM' })` builds the list at runtime. No hardcoded wallet registry; new wallets installed by the user appear without an SDK update.
|
|
92
92
|
|
|
93
|
-
Other chains ship a curated connector list (Bitcoin: Xverse / Unisat / OKX, Sui: dapp-kit's standard connectors, Solana: wallet-adapter's standard connectors, etc.). For each connector, `isInstalled` reflects whether the underlying extension/wallet is detected. `sortConnectors(list, { preferred })` puts installed connectors first — call it once in your render path; the result is stable per render.
|
|
93
|
+
Other chains ship a curated connector list (Bitcoin: Xverse / Unisat / OKX / Hana, Sui: dapp-kit's standard connectors, Solana: wallet-adapter's standard connectors, etc.). For each connector, `isInstalled` reflects whether the underlying extension/wallet is detected. `sortConnectors(list, { preferred })` puts installed connectors first — call it once in your render path; the result is stable per render.
|
|
94
94
|
|
|
95
95
|
---
|
|
96
96
|
|
|
@@ -53,10 +53,10 @@ Bitcoin's signing flow inspects the connected address and picks the right method
|
|
|
53
53
|
|
|
54
54
|
| Address type | Signing method | Connectors that support it |
|
|
55
55
|
|--------------|----------------|----------------------------|
|
|
56
|
-
| P2WPKH (native segwit, `bc1q…`) | BIP-322 | Unisat, Xverse, OKX |
|
|
57
|
-
| P2TR (taproot, `bc1p…`) | BIP-322 | Unisat, Xverse, OKX |
|
|
58
|
-
| P2SH (legacy multi-sig, `3…`) | ECDSA | Unisat, Xverse, OKX |
|
|
59
|
-
| P2PKH (legacy, `1…`) | ECDSA | Unisat, Xverse, OKX |
|
|
56
|
+
| P2WPKH (native segwit, `bc1q…`) | BIP-322 | Unisat, Xverse, OKX, Hana |
|
|
57
|
+
| P2TR (taproot, `bc1p…`) | BIP-322 | Unisat, Xverse, OKX, Hana |
|
|
58
|
+
| P2SH (legacy multi-sig, `3…`) | ECDSA | Unisat, Xverse, OKX, Hana |
|
|
59
|
+
| P2PKH (legacy, `1…`) | ECDSA | Unisat, Xverse, OKX, Hana |
|
|
60
60
|
|
|
61
61
|
If a custom connector implements only one of the two methods, calling `signMessage` from a wrongly-typed address surfaces the error inline.
|
|
62
62
|
|
|
@@ -124,7 +124,7 @@ import { IconHanaXConnector } from '@sodax/wallet-sdk-react/xchains/icon';
|
|
|
124
124
|
|
|
125
125
|
| Sub-path | Beyond `XService`/`XConnector` |
|
|
126
126
|
|---|---|
|
|
127
|
-
| `/xchains/bitcoin` | `XverseXConnector`, `UnisatXConnector`, `OKXXConnector` (
|
|
127
|
+
| `/xchains/bitcoin` | `XverseXConnector`, `UnisatXConnector`, `OKXXConnector`, `BitcoinHanaXConnector` (4 wallet connectors), hook `useBitcoinXConnectors`, type `BtcWalletAddressType` |
|
|
128
128
|
| `/xchains/evm` | `createWagmiConfig` (function — also exported as alias `createWagmi`) |
|
|
129
129
|
| `/xchains/icon` | `CHAIN_INFO` (value), `SupportedChainId` (enum) |
|
|
130
130
|
| `/xchains/stacks` | `STACKS_PROVIDERS` (value), hook `useStacksXConnectors`, type `StacksProviderConfig` |
|
|
@@ -10,7 +10,7 @@ Chains supported by `@sodax/wallet-sdk-react` v2 — their `ChainType` family an
|
|
|
10
10
|
|
|
11
11
|
| ChainType | Networks (examples) | React adapter mounted |
|
|
12
12
|
|---|---|---|
|
|
13
|
-
| `EVM` | Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia | wagmi |
|
|
13
|
+
| `EVM` | Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera | wagmi |
|
|
14
14
|
| `SOLANA` | Solana mainnet | `@solana/wallet-adapter-react` |
|
|
15
15
|
| `SUI` | Sui mainnet/testnet | `@mysten/dapp-kit` |
|
|
16
16
|
| `BITCOIN` | Bitcoin mainnet | (none — direct extension probes) |
|
|
@@ -56,7 +56,7 @@ ChainKeys.BITCOIN_MAINNET; // BITCOIN
|
|
|
56
56
|
// …etc
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
Naming pattern: `<NETWORK>_MAINNET`.
|
|
59
|
+
Naming pattern: `<NETWORK>_MAINNET`. EVM has 13 entries (Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera); the other 8 families each have one. Inspect `@sodax/types` for the authoritative list.
|
|
60
60
|
|
|
61
61
|
---
|
|
62
62
|
|
|
@@ -37,7 +37,7 @@ const connectors = useXConnectors({ xChainType: 'EVM' });
|
|
|
37
37
|
// IXConnector[] — already filtered to enabled chain
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
For the per-chain class names (only needed for `instanceof` or custom-connector-list use cases), see [`api-surface.md`](./api-surface.md) § "Sub-path exports" and the worked example in [`../recipes/sub-path-imports.md`](../recipes/sub-path-imports.md). Bitcoin's `BitcoinXConnector` is the only abstract base — its concrete subclasses (Unisat, Xverse, OKX) override per-wallet signing methods (see [`sign-message.md`](../recipes/sign-message.md)).
|
|
40
|
+
For the per-chain class names (only needed for `instanceof` or custom-connector-list use cases), see [`api-surface.md`](./api-surface.md) § "Sub-path exports" and the worked example in [`../recipes/sub-path-imports.md`](../recipes/sub-path-imports.md). Bitcoin's `BitcoinXConnector` is the only abstract base — its concrete subclasses (Unisat, Xverse, OKX, Hana) override per-wallet signing methods (see [`sign-message.md`](../recipes/sign-message.md)).
|
|
41
41
|
|
|
42
42
|
---
|
|
43
43
|
|
|
@@ -10,7 +10,7 @@ The identifiers are **open**: any string works. The table below lists every bran
|
|
|
10
10
|
|
|
11
11
|
| Identifier | Chains it matches | Underlying connector id / name |
|
|
12
12
|
|---|---|---|
|
|
13
|
-
| `'hana'` | EVM, ICON, Sui, Stellar | EVM via EIP-6963 RDNS (e.g. `io.havah.hana`); ICON id `hana`; Sui/Stellar — connector names containing "Hana" |
|
|
13
|
+
| `'hana'` | EVM, ICON, Sui, Stellar, Bitcoin | EVM via EIP-6963 RDNS (e.g. `io.havah.hana`); ICON id `hana`; Bitcoin id `hana-bitcoin`; Sui/Stellar — connector names containing "Hana" |
|
|
14
14
|
| `'phantom'` | EVM, Solana | EVM RDNS `app.phantom`; Solana adapter name `Phantom` |
|
|
15
15
|
| `'metamask'` | EVM, Injective | EVM RDNS `io.metamask`; Injective `Wallet.Metamask` strategy |
|
|
16
16
|
| `'xverse'` | Bitcoin, Stacks | Bitcoin id `xverse`; Stacks id `XverseProviders.BitcoinProvider` |
|