@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.
Files changed (29) hide show
  1. package/package.json +1 -1
  2. package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +2 -2
  3. package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +2 -2
  4. package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +1 -1
  5. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +1 -1
  6. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +1 -1
  7. package/skills/sodax-sdk/SKILL.md +1 -1
  8. package/skills/sodax-sdk/integration/knowledge/architecture.md +6 -6
  9. package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +22 -2
  10. package/skills/sodax-sdk/integration/knowledge/features/money-market.md +1 -1
  11. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +11 -6
  12. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +27 -0
  13. package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
  14. package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +5 -4
  15. package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +7 -6
  16. package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +1 -1
  17. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +1 -1
  18. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +1 -0
  19. package/skills/sodax-wallet-sdk-core/evm/SKILL.md +3 -3
  20. package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
  21. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
  22. package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
  23. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
  24. package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +1 -1
  25. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +4 -4
  26. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +1 -1
  27. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +2 -2
  28. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
  29. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "2.0.0-rc.19",
7
+ "version": "2.0.0-rc.20",
8
8
  "license": "MIT",
9
9
  "description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
10
10
  "keywords": [
@@ -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' | 'executed' | 'failed'
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 `executed` / `failed` |
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 `executed` / `failed`:
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 `executed` / `failed`) |
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 `executed` / `failed` |
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 13 reason-only codes.
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) + 19 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.'
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; 19 spoke chains route through it.
7
+ 1. [Hub-and-spoke model](#1-hub-and-spoke-model) — Sonic is the hub; 20 spoke chains route through it.
8
8
  2. [`SpokeService` router](#2-spokeservice-router) — single internal dispatcher; no per-chain provider classes.
9
9
  3. [`Sodax` facade and service graph](#3-sodax-facade-and-service-graph) — one instance owns every feature service.
10
10
  4. [`ConfigService`](#4-configservice) — dynamic config from backend with packaged-defaults fallback.
@@ -50,7 +50,7 @@ For most consumers, this whole pipeline is one method call (`sodax.swaps.swap(..
50
50
 
51
51
  ### Supported chains
52
52
 
53
- 20 total. EVM (12): Sonic (hub), Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia. Non-EVM (8): Solana, Sui, Stellar, ICON, Injective, NEAR, Stacks, Bitcoin. See [`reference/`](reference/) § "Chain keys" for the full table with relay IDs and address-type mapping.
53
+ 21 total. EVM (13): Sonic (hub), Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia, Hedera. Non-EVM (8): Solana, Sui, Stellar, ICON, Injective, NEAR, Stacks, Bitcoin. See [`reference/`](reference/) § "Chain keys" for the full table with relay IDs and address-type mapping.
54
54
 
55
55
  ---
56
56
 
@@ -62,7 +62,7 @@ Instead, the SDK has **one** `SpokeService` instance (owned by `Sodax`) which ho
62
62
 
63
63
  ```
64
64
  SpokeService
65
- ├── EvmSpokeService (handles all 12 EVM chains)
65
+ ├── EvmSpokeService (handles all 13 EVM chains)
66
66
  ├── SonicSpokeService (special-cased for the hub)
67
67
  ├── SolanaSpokeService
68
68
  ├── SuiSpokeService
@@ -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 — Non-EVM quirks
1
+ # Chain specifics — chain quirks
2
2
 
3
- EVM chains (12 of them) work uniformly through `IEvmWalletProvider`. Non-EVM chains have particularities you need to handle. This file documents each chain family's quirks.
3
+ EVM chains mostly work uniformly through `IEvmWalletProvider`, with **one** native-value exception (Hedera, below). Non-EVM chains have more particularities you need to handle. This file documents each chain family's quirks.
4
4
 
5
5
  ## Section index
6
6
 
7
+ EVM:
8
+
9
+ 0. [Hedera HBAR msg.value scaling](#0-hedera-hbar-msgvalue-scaling) — `HEDERA_MAINNET`. The only EVM-family quirk: native deposits scale `msg.value` by 10^10. Handled automatically by the SDK.
10
+
11
+ Non-EVM:
12
+
7
13
  1. [Stellar trustline](#1-stellar-trustline) — `STELLAR_MAINNET`. Required before receiving any non-XLM asset.
8
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 19 spoke chains. Position state lives on the hub.
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`. This differs from the feature services (`sodax.swaps`, etc.), whose errors
13
- carry their own `feature` (`'swap'`, …) — the swaps **HTTP client** is uniformly `feature: 'backend'`.
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 === 'executed') { /* settled */ }
107
- // Lifecycle: 'pending' → 'relaying' → 'relayed' → 'posting_execution' → 'executed' | 'failed'.
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'` / `'executed'` / `'failed'` (`'executed'` / `'failed'` terminal). |
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
- 20 supported chains. The `ChainKey` type is the union of every `ChainKeys.*` value. **`SpokeChainKey` is the same union — it includes Sonic.** The "spoke" naming refers to how feature services type their `srcChainKey` parameter (they accept the hub too — bridge / swap / staking etc. all run from Sonic as source via the hub-wallet abstraction). When you specifically need "EVM chains excluding the hub" use `EVM_SPOKE_ONLY_CHAIN_KEYS` / `isEvmSpokeOnlyChainKeyType`.
3
+ 21 supported chains. The `ChainKey` type is the union of every `ChainKeys.*` value. **`SpokeChainKey` is the same union — it includes Sonic.** The "spoke" naming refers to how feature services type their `srcChainKey` parameter (they accept the hub too — bridge / swap / staking etc. all run from Sonic as source via the hub-wallet abstraction). When you specifically need "EVM chains excluding the hub" use `EVM_SPOKE_ONLY_CHAIN_KEYS` / `isEvmSpokeOnlyChainKeyType`.
4
4
 
5
5
  | `ChainKeys.*` | String value | Family | Hub vs spoke | Address type |
6
6
  |---|---|---|---|---|
@@ -16,6 +16,7 @@
16
16
  | `LIGHTLINK_MAINNET` | `'lightlink'` | EVM | spoke | `0x${string}` |
17
17
  | `REDBELLY_MAINNET` | `'redbelly'` | EVM | spoke | `0x${string}` |
18
18
  | `KAIA_MAINNET` | `'0x2019.kaia'` | EVM | spoke | `0x${string}` |
19
+ | `HEDERA_MAINNET` | `'hedera'` | EVM | spoke | `0x${string}` |
19
20
  | `SOLANA_MAINNET` | `'solana'` | SOLANA | spoke | base58 PublicKey string |
20
21
  | `SUI_MAINNET` | `'sui'` | SUI | spoke | `0x${string}` (32-byte) |
21
22
  | `STELLAR_MAINNET` | `'stellar'` | STELLAR | spoke | `G…` |
@@ -35,9 +36,9 @@
35
36
 
36
37
  | Type | What it is |
37
38
  |---|---|
38
- | `ChainKey` | Union of all `ChainKeys.*` values (20 chains). |
39
- | `SpokeChainKey` | The full union of all 20 chain keys, **including** `'sonic'` — identical to `ChainKey` (see the note at the top of this file). |
40
- | `EvmChainKey` | Subset of `ChainKey` for the 12 EVM chains. |
39
+ | `ChainKey` | Union of all `ChainKeys.*` values (21 chains). |
40
+ | `SpokeChainKey` | Same union as `ChainKey` — includes Sonic (21 chains). For "EVM chains excluding the hub" use `EvmSpokeOnlyChainKey`. |
41
+ | `EvmChainKey` | Subset of `ChainKey` for the 13 EVM chains. |
41
42
  | `HubChainKey` | The literal `'sonic'`. |
42
43
 
43
44
  ### Chain-family helpers
@@ -1,9 +1,10 @@
1
1
  # Error codes
2
2
 
3
- All 13 codes the SDK can emit. Each error is `SodaxError<C>` where `C` is one of these. The producing feature is on `error.feature`.
3
+ All 14 codes the SDK can emit. Each error is `SodaxError<C>` where `C` is one of these. The producing feature is on `error.feature`.
4
4
 
5
5
  | Code | Meaning | Common `error.context` fields | Retry advice |
6
6
  |---|---|---|---|
7
+ | `USER_REJECTED` | User cancelled the wallet prompt (signing / approval / connection). Classified at the source by `intentCreationFailed` / `approveFailed` wrappers via a built-in detector that recognises viem `4001` / `UserRejectedRequestError`, ICON Hana `CANCEL_SIGNING` / `-31002`, and name + message patterns from Solana / Sui / Stellar / Stacks / NEAR / Injective wallets. | `phase` (set to whichever phase the wrapper was wrapping: `'intentCreation'` or `'approve'`), `action` | No — user-initiated. Render a "Cancelled" UI, not a failure. |
7
8
  | `VALIDATION_FAILED` | Pre-flight invariant tripped (input shape, unsupported chain, etc.). | `field`, `reason`, `phase: 'validate'` | No — fix the input. |
8
9
  | `INTENT_CREATION_FAILED` | Building the intent / payload failed. | `phase: 'intentCreation'`, `action` | Sometimes — depends on root cause (`error.cause`). |
9
10
  | `EXECUTION_FAILED` | Orchestrator-level catch-all (multi-step op didn't complete). | `action`, `phase: 'execution'` or `'postExecution'` | Sometimes — inspect cause. |
@@ -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 13 reason-only error codes. See § 3. |
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 12 SODAX EVM chains — the Sonic hub plus 11 EVM spoke chains (Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia). 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).'
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 SODAX EVM chains — the Sonic hub plus 11 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.
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 12 EVM chains (the Sonic hub plus 11 EVM spokes) via `chainId: EvmChainKey` (`ChainKeys.SONIC_MAINNET`, …).
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 (12 chains) | `EvmWalletProvider` | `viem` |
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 all **12** SODAX EVM spoke chains via `getEvmViemChain()`.
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
 
@@ -20,7 +20,7 @@ pnpm add @sodax/sdk
20
20
 
21
21
  ---
22
22
 
23
- ## EVM (12 chains)
23
+ ## EVM (13 chains)
24
24
 
25
25
  ```ts
26
26
  import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
@@ -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, 12 chains)
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
- > 20 spoke chains total = 12 EVM + 8 non-EVM. The hub chain (Sonic) is counted with EVM.
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` (3 wallet connectors), hook `useBitcoinXConnectors`, type `BtcWalletAddressType` |
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`. Most chain keys are EVM (Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia); each non-EVM family has one. Inspect `@sodax/types` for the authoritative, current list and count.
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` |